@fuzo/soccer-board 0.1.0-alpha.2

package/README.md

@@ -0,0 +1,335 @@
+# ⚽ Soccer Board Angular
+
+A beautiful, interactive soccer field component for Angular applications. Create tactical formations, manage player positions, and export your field as PNG images. Built with modern Angular features (signals, standalone components) and styled with Tailwind CSS.
+
+![Angular](https://img.shields.io/badge/Angular-21.0+-red.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![npm](https://img.shields.io/badge/npm-package-green.svg)
+
+## ✨ Features
+
+- 🎨 **FIFA-compliant field** with accurate dimensions and markings
+- 🔄 **Portrait & Landscape** orientations
+- 👥 **Drag & Drop** players onto the field
+- 🎯 **Tactical position detection** (GK, CB, RB, LB, CDM, CM, CAM, LW, RW, ST, etc.)
+- 📱 **Responsive design** with `fit="contain"` mode
+- 🎨 **Beautiful player cards** with photos, numbers, and positions
+- 📤 **Export to PNG** with high-quality images
+- 🎛️ **Fully configurable** layout and behavior
+- ⚡ **100% Reactive** using Angular signals
+- 🎨 **Tailwind CSS** styling (optional, works without it)
+
+## 📦 Installation
+
+```bash
+npm install fuzo-soccer-board
+```
+
+That's it! The library includes `html2canvas-pro` as a dependency for PNG export functionality (supports modern CSS color functions like `oklab`).
+
+## 🚀 Quick Start
+
+### 1. Import the Component
+
+```typescript
+import { SoccerBoardComponent, SoccerBoardPlayer, SoccerBoardOrientation, SoccerBoardTeamSide } from 'fuzo-soccer-board';
+
+@Component({
+  selector: 'app-my-component',
+  standalone: true,
+  imports: [SoccerBoardComponent],
+  template: `
+    <fuzo-soccer-board
+      [players]="players"
+      [orientation]="SoccerBoardOrientation.Landscape"
+      (playerPositioned)="onPlayerPositioned($event)"
+      (imageExported)="onImageExported($event)"
+    />
+  `,
+})
+export class MyComponent {
+  SoccerBoardOrientation = SoccerBoardOrientation;
+  
+  players: SoccerBoardPlayer[] = [
+    {
+      id: '1',
+      name: 'Messi',
+      number: 10,
+      photo: '/path/to/photo.png',
+      preferredPosition: 'ST',
+    },
+  ];
+
+  onPlayerPositioned(event: any) {
+    console.log('Player positioned:', event);
+  }
+
+  onImageExported(event: { blob: Blob; dataUrl: string }) {
+    // Handle exported image
+    console.log('Image exported:', event.dataUrl);
+  }
+}
+```
+
+### 2. Basic Usage
+
+```html
+<fuzo-soccer-board
+  [players]="players"
+  [orientation]="SoccerBoardOrientation.Landscape"
+  [showPositions]="true"
+  [fit]="SoccerBoardFitMode.Contain"
+/>
+```
+
+## 📚 API Reference
+
+### Inputs
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `players` | `SoccerBoardPlayer[]` | `[]` | Array of players to display |
+| `orientation` | `SoccerBoardOrientationType` | `SoccerBoardOrientation.Landscape` | Field orientation: `'portrait'` or `'landscape'` |
+| `teamSide` | `SoccerBoardTeamSideType` | `null` | Show specific side: `SoccerBoardTeamSide.Home`, `SoccerBoardTeamSide.Away`, or `null` (both) |
+| `showPositions` | `boolean` | `false` | Show tactical position zones |
+| `fit` | `SoccerBoardFitModeType` | `null` | Responsive mode: `SoccerBoardFitMode.Contain` or `null` |
+| `showPlayersSidebar` | `boolean` | `true` | Show sidebar with available players |
+| `playersPosition` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | Position of players sidebar |
+| `playersColumns` | `number` | `2` | Number of columns in players grid |
+| `maxPlayersPerSide` | `number` | `7` | Maximum players allowed per side (HOME/AWAY) |
+
+### Outputs
+
+| Output | Event Data | Description |
+|--------|-----------|-------------|
+| `playerPositioned` | `{ playerId: string; fieldX: number; fieldY: number; side: SoccerBoardTeamSide; position: string }` | Emitted when a player is dropped on the field |
+| `playerRemovedFromField` | `{ playerId: string }` | Emitted when a player is removed from the field |
+| `imageExported` | `{ blob: Blob; dataUrl: string }` | Emitted when field is exported to PNG |
+
+### Public Methods
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `exportToPNG()` | - | `Promise<void>` | Exports the field as PNG image (also triggers `imageExported` event) |
+
+### Player Model
+
+```typescript
+interface SoccerBoardPlayer {
+  id: string;                    // Unique identifier
+  name: string;                   // Player name
+  number?: number;                // Jersey number
+  photo?: string;                 // Photo URL
+  preferredPosition?: string;     // Natural position (shown when off field)
+  fieldPosition?: string;         // Position on field (set when placed)
+  fieldX?: number;                // Normalized X coordinate (0-100)
+  fieldY?: number;                // Normalized Y coordinate (0-100)
+  side?: SoccerBoardTeamSide;     // Which half: SoccerBoardTeamSide.Home or SoccerBoardTeamSide.Away
+}
+```
+
+### Enums & Types
+
+```typescript
+enum SoccerBoardOrientation {
+  Portrait = 'portrait',
+  Landscape = 'landscape',
+}
+
+enum SoccerBoardTeamSide {
+  Home = 'home',
+  Away = 'away',
+}
+
+enum SoccerBoardFitMode {
+  Contain = 'contain',
+}
+
+enum SoccerBoardPlayerSize {
+  Small = 'small',
+  Medium = 'medium',
+  Large = 'large',
+}
+```
+
+## 🎯 Examples
+
+### Basic Field
+
+```html
+<fuzo-soccer-board [players]="players" />
+```
+
+### With Position Zones
+
+```html
+<fuzo-soccer-board
+  [players]="players"
+  [showPositions]="true"
+/>
+```
+
+### Responsive Field
+
+```html
+<fuzo-soccer-board
+  [players]="players"
+  [fit]="SoccerBoardFitMode.Contain"
+/>
+```
+
+### Custom Layout
+
+```html
+<fuzo-soccer-board
+  [players]="players"
+  [showPlayersSidebar]="true"
+  [playersPosition]="'right'"
+  [playersColumns]="3"
+/>
+```
+```
+
+### Handle Player Positioning
+
+```typescript
+onPlayerPositioned(event: {
+  playerId: string;
+  fieldX: number;
+  fieldY: number;
+  side: SoccerBoardTeamSide;
+  position: string;
+}) {
+  // Update player in your data
+  const player = this.players.find(p => p.id === event.playerId);
+  if (player) {
+    player.fieldX = event.fieldX;
+    player.fieldY = event.fieldY;
+    player.side = event.side;
+    player.fieldPosition = event.position;
+  }
+}
+```
+
+### Export to PNG
+
+```typescript
+// Method 1: Call the method directly
+@ViewChild(SoccerBoardComponent) soccerBoard!: SoccerBoardComponent;
+
+async exportField() {
+  await this.soccerBoard.exportToPNG();
+}
+
+// Method 2: Handle the event
+onImageExported(event: { blob: Blob; dataUrl: string }) {
+  // Use blob for upload
+  const formData = new FormData();
+  formData.append('image', event.blob, 'soccer-field.png');
+  
+  // Or use dataUrl for display/preview
+  this.imagePreview = event.dataUrl;
+  
+  // Or send via email, etc.
+  this.sendEmailWithImage(event.dataUrl);
+}
+```
+
+### Custom Styling
+
+You can customize the field using CSS custom properties:
+
+```css
+fuzo-soccer-board {
+  --soccer-board-width: 800px;
+  --soccer-board-max-width: 1200px;
+  --soccer-board-padding: 20px;
+}
+```
+
+## 🎨 Styling
+
+The component uses Tailwind CSS for player cards, but the field itself is styled with pure CSS/SCSS. If you're using Tailwind in your project, the player cards will automatically use your Tailwind configuration.
+
+### Without Tailwind
+
+The component works without Tailwind CSS, but player cards will have minimal styling. You can add your own styles:
+
+```css
+lib-soccer-board-player {
+  /* Your custom styles */
+}
+```
+
+## 🔧 Advanced Usage
+
+### Programmatic Player Positioning
+
+```typescript
+// Set player position programmatically
+const player = this.players.find(p => p.id === '1');
+if (player) {
+  player.fieldX = 50;  // Center X
+  player.fieldY = 50;  // Center Y
+  player.side = SoccerBoardTeamSide.Home;
+  player.fieldPosition = 'CM';
+}
+```
+
+### Filter Players by Side
+
+```typescript
+// Get only players on HOME side
+const homePlayers = this.players.filter(
+  p => p.side === SoccerBoardTeamSide.Home && p.fieldX !== undefined
+);
+```
+
+### Remove Player from Field
+
+```typescript
+removePlayer(playerId: string) {
+  const player = this.players.find(p => p.id === playerId);
+  if (player) {
+    player.fieldX = undefined;
+    player.fieldY = undefined;
+    player.side = undefined;
+    player.fieldPosition = undefined;
+  }
+}
+```
+
+## 🐛 Troubleshooting
+
+### Images not loading
+
+Make sure player photos are accessible and CORS is configured correctly if loading from external sources.
+
+### Export not working
+
+- Ensure `html2canvas-pro` is installed
+- Check browser console for errors
+- Make sure images are loaded before exporting
+
+### Field not responsive
+
+- Use `[fit]="SoccerBoardFitMode.Contain"` for responsive behavior
+- Ensure parent container has defined dimensions
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📝 License
+
+MIT License - see LICENSE file for details
+
+## 🙏 Acknowledgments
+
+- Built with [Angular](https://angular.io/)
+- Field dimensions based on FIFA regulations
+- Export functionality powered by [html2canvas-pro](https://www.npmjs.com/package/html2canvas-pro)
+
+---
+
+Made with ⚽ by the community