npm package: @gamifyhost/gamifyhost-widget
Description: An embeddable React widget that brings gamification features to any website
Author: GamifyHost Team
Latest version: 1.0.6

# GamifyHost Widget

An embeddable React widget that brings gamification features to any website. Includes interactive games, leaderboards, and a complete reward system with style isolation via Shadow DOM.

## Features

- 🎮 **Multiple Games**
  - Neon Wheel - Spin-to-win prize wheel
  - Cosmic Slots - Space-themed slot machine
  - Enigma Boxes - Mystery box game
- 🏆 **Leaderboard System** - Track and display top players
- ⚡ **Energy Meter** - Built-in game balance system
- 🎨 **Theme Support** - Light/Dark mode with customizable styling
- 🔒 **Style Isolation** - Shadow DOM prevents CSS conflicts
- 📱 **Responsive Design** - Works on all device sizes

## Technology Stack

- **React 19** - UI framework
- **TypeScript** - Type safety
- **Vite** - Build tool and dev server
- **Tailwind CSS 4** - Styling
- **Shadow DOM** - Style encapsulation

## Installation

### Embed in Your Website

Add the widget script to your HTML:

```html
<script
  src="https://cdn.gamifyhost.com/widget.js"
  data-public-key="your_public_key_here"
  data-user-id="unique_user_id"
  data-initial-balance="1000"
  data-api-url="https://api.gamifyhost.com"
  data-container="gamifyhost"
></script>
```

The widget will automatically initialize and render in the specified container.

### Configuration Options

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `data-public-key` | ✅ Yes | - | Your GamifyHost public API key |
| `data-user-id` | ❌ No | - | Unique identifier for the current user |
| `data-initial-balance` | ❌ No | `0` | Starting balance for the user |
| `data-api-url` | ❌ No | `https://api.gamifyhost.com` | API endpoint URL |
| `data-container` | ❌ No | `gamifyhost` | ID of the container element |

### Example Configurations

**Basic Setup:**
```html
<script
  src="https://cdn.gamifyhost.com/widget.js"
  data-public-key="pk_live_abc123"
></script>
```

**With User Session:**
```html
<script
  src="https://cdn.gamifyhost.com/widget.js"
  data-public-key="pk_live_abc123"
  data-user-id="user_xyz789"
  data-initial-balance="500"
></script>
```

**Custom Container:**
```html
<div id="my-games-widget"></div>
<script
  src="https://cdn.gamifyhost.com/widget.js"
  data-public-key="pk_live_abc123"
  data-container="my-games-widget"
></script>
```

## Development

### Prerequisites

- Node.js 18+ 
- npm, yarn, or pnpm

### Setup

1. Clone the repository:
```bash
git clone https://github.com/gamifyhost/gamifyhost-widget.git
cd gamifyhost-widget
```

2. Install dependencies:
```bash
npm install
```

3. Start the development server:
```bash
npm run dev
```

4. Open `test.html` in your browser to see the widget in action.

### Available Scripts

- `npm run dev` - Start Vite development server
- `npm run build` - Build for production
- `npm run preview` - Preview production build locally

### Project Structure

```
gamifyhost-widget/
├── src/
│   ├── components/      # React components
│   │   └── EnergyMeter.tsx
│   ├── hooks/          # Custom React hooks
│   │   └── useGameSounds.ts
│   ├── lib/            # Core libraries
│   │   ├── api.ts      # API client
│   │   ├── config.ts   # SDK configuration
│   │   ├── context.tsx # React context
│   │   └── theme.tsx   # Theme management
│   ├── pages/          # Game pages
│   │   ├── HomePage.tsx
│   │   ├── NeonWheelPage.tsx
│   │   ├── CosmicSlotsPage.tsx
│   │   ├── EnigmaBoxesPage.tsx
│   │   └── LeaderboardPage.tsx
│   ├── App.tsx         # Main app component
│   ├── router.tsx      # Client-side routing
│   ├── widget.ts       # Widget initialization
│   ├── fonts.ts        # Font injection
│   └── globals.css     # Global styles
├── test.html           # Test page for development
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
```

## How It Works

### Shadow DOM Isolation

The widget uses Shadow DOM to prevent CSS conflicts with the host page:

1. Widget script is loaded via `<script>` tag
2. Shadow root is attached to the container element
3. All styles and fonts are injected into the shadow root
4. React app renders inside the shadow DOM

This ensures the widget's styles won't affect your page and vice versa.

### API Integration

The widget communicates with the GamifyHost API to:
- Authenticate users via public key
- Track game results and balances
- Update leaderboards
- Sync user progress

### Theme System

Supports light and dark modes with automatic detection:
- Uses CSS custom properties for theming
- Theme styles injected into shadow root
- Persistent theme selection via localStorage

## Customization

### Styling

The widget uses Tailwind CSS with custom design tokens. To customize:

1. Modify `src/globals.css` for global theme variables
2. Update component styles in respective `.tsx` files
3. Rebuild the widget: `npm run build`

### Games

To add new games:

1. Create a new page component in `src/pages/`
2. Add route in `src/router.tsx`
3. Update the navigation in `src/pages/HomePage.tsx`
4. Implement game logic with API integration

## Browser Support

- Chrome/Edge 88+
- Firefox 85+
- Safari 14+
- All browsers with Shadow DOM support

## Contributing

We welcome contributions! Please follow these steps:

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

### Development Guidelines

- Follow TypeScript best practices
- Maintain existing code style
- Test your changes thoroughly
- Update documentation as needed
- Keep commits focused and atomic

## License

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

## Support

For questions, issues, or feature requests:

- 📧 Email: support@gamifyhost.com
- 🐛 Issues: [GitHub Issues](https://github.com/gamifyhost/gamifyhost-widget/issues)
- 📖 Documentation: [docs.gamifyhost.com](https://docs.gamifyhost.com)

## Acknowledgments

- Built with [React](https://react.dev/)
- Styled with [Tailwind CSS](https://tailwindcss.com/)
- Bundled with [Vite](https://vitejs.dev/)
- Fonts from [Google Fonts](https://fonts.google.com/)

---

Made with ⚡ by the GamifyHost team