npm package: @hogrid/react-hotspot-viewer-image
Description: React Hotspot viewer component with animated pins, desktop tooltips and mobile drawer.
Author: Emerson Nunes
Latest version: 1.0.0-beta.0

# react-hotspot-viewer-image

## react-hotspot-viewer-image

A React component that displays interactive hotspots over an image with an animated “ping” effect. On desktop, clicking a hotspot shows a tooltip with title and description; on mobile, it opens a Shadcn UI Drawer. Hotspots maintain their relative positions responsively as the image resizes.

## Features

- **Animated Hotspots**: Pulsing “ping” animation behind each hotspot pin.
- **Desktop Tooltips**: Click a hotspot to open a styled tooltip; click outside or the close icon to dismiss.
- **Mobile Drawers**: On screens ≤768px, hotspots open a Shadcn UI Drawer for title and description.
- **Responsive**: Positions are percentage-based and adjust with image resizing.
- **Zero Dependencies**: Only relies on peer dependencies.

## Installation

Install via npm or yarn:

```bash
# npm
npm install react-hotspot-viewer-image

# yarn
yarn add react-hotspot-viewer-image
```

### Peer Dependencies

Ensure the following are installed in your project:

- `react` `^17 || ^18`
- `react-dom` `^17 || ^18`
- `@shadcn/ui` (for the Drawer component)
- _(Optional)_ `tailwindcss` `>=3.0.0` if you use Tailwind in your app
- _(Optional)_ `class-variance-authority`, `lucide-react` if you extend styling/icons

## Usage

Import the component and provide an array of hotspots:

```tsx
import React from 'react';
import { HotspotViewer, Hotspot } from 'react-hotspot-viewer-image';

const hotspots: Hotspot[] = [
  {
    id: 1,
    title: 'Title 01',
    description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
    position: { top: '30%', left: '50%' },
  },
  {
    id: 2,
    title: 'Title 02',
    description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
    position: { top: '20%', left: '80%' },
  },
  // add more hotspots as needed...
];

export default function App() {
  return (
    <div style={{ maxWidth: '800px', margin: '0 auto' }}>
      <HotspotViewer
        hotspots={hotspots}
        imageSrc="/your/image/path.jpg"
      />
    </div>
  );
}
```

### Props

#### `hotspots` (required)

Type: `Hotspot[]`

Array of hotspot objects:

| Property    | Type                | Description                                                      |
| ----------- | ------------------- | ---------------------------------------------------------------- |
| `id`        | `number`            | Unique identifier for each hotspot.                              |
| `title`     | `string`            | Title displayed in the tooltip or drawer header.                 |
| `description`| `string`           | Text displayed in the tooltip body or drawer description.        |
| `position`  | `{ top: string; left: string; }` | CSS values (`%` or `px`) for positioning relative to the image. |

#### `imageSrc` (optional)

Type: `string`
Default: `'/img/suplemento-premiado/section-05-thumb.svg'`

URL or path to the base image over which hotspots are placed.

## Configuration & Styling

- The component uses **styled-jsx** for scoped styles. To customize, you can:
  - Pass a different `imageSrc`.
  - Override CSS variables or target `.hotspot-tooltip`, `.hotspot-pin`, `.hotspot-ping` in your global styles.
- Ensure your project supports client components (e.g., Next.js 13+ with `use client`).

## Development

1. **Clone the repo**
   ```bash
   git clone https://github.com/your-username/react-hotspot-viewer-image.git
   cd react-hotspot-viewer-image
   ```
2. **Install dependencies**
   ```bash
   npm install
   ```
3. **Build**
   ```bash
   npm run build
   ```
4. **Link locally** (for testing in another project)
   ```bash
   npm link
   ```

## Contributing

Contributions, issues, and feature requests are welcome! Please follow the standard gitflow:

1. Fork the repository.
2. Create a feature branch: `git checkout -b feat/my-new-feature`
3. Commit your changes: `git commit -m 'Add some feature'`
4. Push to the branch: `git push origin feat/my-new-feature`
5. Open a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.