@gamifyhost/gamifyhost-widget 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GamifyHost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# 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