@beta-gamer/angular 0.1.2 → 0.1.4

package/README.md

@@ -43,7 +43,16 @@ import { BetaGamerService, ChessBoardComponent } from '@beta-gamer/angular';
 @Component({
   standalone: true,
   imports: [ChessBoardComponent],
-  template: `<bg-chess-board style="width:100%;height:500px" />`,
+  template: `
+    <bg-chess-board
+      style="width:100%;height:500px"
+      [showCoords]="true"
+      [showLastMove]="true"
+      [showLegalMoves]="true"
+      orientation="auto"
+      (onLeave)="handleLeave()"
+    />
+  `,
 })
 export class AppComponent implements OnInit {
   private svc = inject(BetaGamerService);
@@ -51,6 +60,10 @@ export class AppComponent implements OnInit {
   ngOnInit() {
     this.svc.init('<SESSION_TOKEN>', 'https://api.beta-gamer.com');
   }
+
+  handleLeave() {
+    // navigate away or show a lobby screen
+  }
 }
 ```
 
@@ -61,9 +74,11 @@ export class AppComponent implements OnInit {
 Injectable service — call `init()` once with the session token.
 
 ```ts
-svc.init(token: string, serverUrl?: string, socketPath?: string)
+svc.init(token: string, serverUrl?: string, socketPath?: string, connectSocket?: boolean)
 ```
 
+> **`connectSocket`** (default `true`) — set to `false` when using only board components. Board components load the game in an iframe with their own socket. A second socket with the same token causes duplicate connections and AFK/turn bugs.
+
 | Signal | Type | Description |
 |--------|------|-------------|
 | `svc.session` | `Signal<Session>` | Current session (game, matchType, players) |
@@ -77,27 +92,64 @@ All components are standalone — import only what you need.
 
 ### Shared (all games)
 
-| Component | Selector | Props | Description |
-|-----------|----------|-------|-------------|
+| Component | Selector | Inputs | Description |
+|-----------|----------|--------|-------------|
 | `PlayerCardComponent` | `<bg-player-card>` | `[player]` (`"self"` \| `"opponent"`) | Player name + active-turn indicator |
 | `TimerComponent` | `<bg-timer>` | `[player]`, `[initialSeconds]?` | Live countdown clock |
 
-### Chess
+### Chess — `ChessBoardComponent`
 
-| Component | Selector | Inputs | Description |
-|-----------|----------|--------|-------------|
-| `ChessBoardComponent` | `<bg-chess-board>` | `[serverUrl]?`, `[showAfkWarning]?` | Interactive chess board (iframe) |
-| `ChessMoveHistoryComponent` | `<bg-chess-move-history>` | — | Scrollable move list |
-| `ChessCapturedPiecesComponent` | `<bg-chess-captured-pieces>` | `[player]` | Captured pieces |
+Selector: `<bg-chess-board>`
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `[serverUrl]` | `string` | `'https://api.beta-gamer.com'` | Base URL of the Beta Gamer server |
+| `[showAfkWarning]` | `boolean` | `true` | Show the built-in AFK countdown banner |
+| `[showCoords]` | `boolean` | `true` | Show rank/file labels (a–h, 1–8) around the board |
+| `[showLastMove]` | `boolean` | `true` | Highlight the from/to squares of the last move |
+| `[showLegalMoves]` | `boolean` | `true` | Show dots on squares where the selected piece can legally move |
+| `[orientation]` | `'white' \| 'black' \| 'auto'` | `'auto'` | Which color is at the bottom. `'auto'` uses the color assigned in `game:started` |
+| `(onLeave)` | `EventEmitter<void>` | — | Emitted when the player taps Leave or exits the game-over modal |
+
+### Checkers — `CheckersBoardComponent`
+
+Selector: `<bg-checkers-board>`
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `[serverUrl]` | `string` | `'https://api.beta-gamer.com'` | Base URL of the Beta Gamer server |
+| `[showAfkWarning]` | `boolean` | `true` | Show the built-in AFK countdown banner |
+| `[showLastMove]` | `boolean` | `true` | Highlight the from/to squares of the last move |
+| `[orientation]` | `'red' \| 'black' \| 'auto'` | `'auto'` | Which color is at the bottom. `'auto'` uses the color assigned in `game:started` |
+| `(onLeave)` | `EventEmitter<void>` | — | Emitted when the player taps Leave or exits the game-over modal |
+
+### Connect 4 — `Connect4BoardComponent`
+
+Selector: `<bg-connect4-board>`
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `[serverUrl]` | `string` | `'https://api.beta-gamer.com'` | Base URL of the Beta Gamer server |
+| `[showAfkWarning]` | `boolean` | `true` | Show the built-in AFK countdown banner |
+| `(onLeave)` | `EventEmitter<void>` | — | Emitted when the player taps Leave or exits the game-over modal |
+
+### Tic-tac-toe — `TictactoeBoardComponent`
+
+Selector: `<bg-tictactoe-board>`
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `[serverUrl]` | `string` | `'https://api.beta-gamer.com'` | Base URL of the Beta Gamer server |
+| `[showAfkWarning]` | `boolean` | `true` | Show the built-in AFK countdown banner |
+| `(onLeave)` | `EventEmitter<void>` | — | Emitted when the player taps Leave or exits the game-over modal |
 
-### Other games
+### Other components
 
 | Component | Selector | Inputs | Game |
 |-----------|----------|--------|------|
-| `CheckersBoardComponent` | `<bg-checkers-board>` | `[serverUrl]?`, `[showAfkWarning]?` | checkers |
-| `Connect4BoardComponent` | `<bg-connect4-board>` | `[serverUrl]?`, `[showAfkWarning]?` | connect4 |
+| `ChessMoveHistoryComponent` | `<bg-chess-move-history>` | — | chess |
+| `ChessCapturedPiecesComponent` | `<bg-chess-captured-pieces>` | `[player]` | chess |
 | `Connect4ScoreComponent` | `<bg-connect4-score>` | — | connect4 |
-| `TictactoeBoardComponent` | `<bg-tictactoe-board>` | `[serverUrl]?`, `[showAfkWarning]?` | tictactoe |
 | `SubwayRunnerGameComponent` | `<bg-subway-runner-game>` | — | subway-runner |
 | `SubwayRunnerScoreComponent` | `<bg-subway-runner-score>` | — | subway-runner |
 | `SubwayRunnerLivesComponent` | `<bg-subway-runner-lives>` | — | subway-runner |

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as _socket_io_component_emitter from '@socket.io/component-emitter';
 import * as _angular_core from '@angular/core';
-import { OnDestroy, OnInit, AfterViewInit, ElementRef } from '@angular/core';
+import { OnDestroy, OnInit, AfterViewInit, EventEmitter, ElementRef } from '@angular/core';
 import { Socket } from 'socket.io-client';
 
 type GameType = 'chess' | 'checkers' | 'connect4' | 'tictactoe' | 'subway-runner';
@@ -41,23 +41,55 @@ interface GameState {
 declare class BetaGamerService implements OnDestroy {
     private _socket;
     private _token;
+    /** Decoded session token payload — null until `init()` is called */
     readonly session: _angular_core.WritableSignal<SessionTokenPayload | null>;
+    /** Live game state updated by server events */
     readonly gameState: _angular_core.WritableSignal<GameState>;
     get token(): string;
+    /** The active socket.io connection — available after `init()` with `connectSocket=true` */
     get socket(): Socket<_socket_io_component_emitter.DefaultEventsMap, _socket_io_component_emitter.DefaultEventsMap> | null;
-    init(token: string, serverUrl?: string, socketPath?: string): void;
+    /**
+     * @description Initialises the service with a session token.
+     * Decodes the token, sets up reactive state, and optionally connects the socket.
+     *
+     * @param token - JWT session token from your backend
+     * @param serverUrl - Base URL of the Beta Gamer server
+     * @param socketPath - socket.io path (default `/socket.io`)
+     * @param connectSocket - Set false to skip socket connection (e.g. for SSR or testing)
+     */
+    init(token: string, serverUrl?: string, socketPath?: string, connectSocket?: boolean): void;
     ngOnDestroy(): void;
 }
 
+/**
+ * @description Displays a player's display name and active-turn indicator.
+ * Styled entirely by the consumer via `data-active` and `data-player` attributes.
+ *
+ * @example
+ * <bg-player-card player="self" />
+ * <bg-player-card player="opponent" />
+ */
 declare class PlayerCardComponent {
+    /** Which player to display — `self` = players[0], `opponent` = players[1] */
     player: 'self' | 'opponent';
     private svc;
     get displayName(): string;
     get isActive(): boolean;
 }
 
+/**
+ * @description Live countdown clock that syncs with the server via `game:clock` socket events.
+ * Falls back to a local 1s interval when the game is active.
+ * Renders a `data-low` attribute when under 30 seconds for easy CSS targeting.
+ *
+ * @example
+ * <bg-timer player="self" [initialSeconds]="600" />
+ */
+
 declare class TimerComponent implements OnInit, OnDestroy {
+    /** Which player's clock to display */
     player: 'self' | 'opponent';
+    /** Starting value in seconds (e.g. 600 = 10 min) */
     initialSeconds: number;
     seconds: number;
     private interval;
@@ -67,66 +99,131 @@ declare class TimerComponent implements OnInit, OnDestroy {
     ngOnDestroy(): void;
 }
 
-declare class ChessBoardComponent implements AfterViewInit {
+/**
+ * @description Shared base class for all iframe-based game board components.
+ *
+ * Handles the full iframe lifecycle:
+ * - Injects the session token into the iframe on load via postMessage
+ * - Listens for `bg:leave` messages from the embed and emits `onLeave`
+ * - Cleans up the message listener on destroy
+ *
+ * Subclasses only need to define their embed URL and any game-specific inputs.
+ */
+
+declare abstract class EmbedBoardBase implements AfterViewInit, OnDestroy {
+    /** Base URL of the Beta Gamer server hosting the embed pages */
     serverUrl: string;
-    showAfkWarning: boolean;
+    /** Emitted when the player clicks Leave inside the embed */
+    onLeave: EventEmitter<void>;
     iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
-    get embedUrl(): string;
+    protected svc: BetaGamerService;
+    /** Subclasses return the full embed URL including query params */
+    abstract get embedUrl(): string;
+    private messageHandler;
     ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    /** Builds a query string from a params object, omitting undefined values */
+    protected buildQuery(params: Record<string, string | undefined>): string;
+}
+
+/**
+ * @description Chess board embed component.
+ * Renders the chess game inside an iframe served by the Beta Gamer embed server.
+ * Supports orientation, coordinate display, last-move highlight, and legal move hints.
+ */
+
+declare class ChessBoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
+    showCoords: boolean;
+    showLastMove: boolean;
+    showLegalMoves: boolean;
+    orientation: 'white' | 'black' | 'auto';
+    get embedUrl(): string;
 }
+
+/**
+ * @description Displays the chess move history in algebraic notation.
+ * Styled entirely by the consumer via the `data-role="move-history"` attribute.
+ */
 declare class ChessMoveHistoryComponent {
 }
+
+/**
+ * @description Displays pieces captured by a given player.
+ * Styled entirely by the consumer via the `data-role="captured-pieces"` attribute.
+ */
 declare class ChessCapturedPiecesComponent {
 }
 
-declare class CheckersBoardComponent implements AfterViewInit {
-    serverUrl: string;
+/**
+ * @description Checkers board embed component.
+ * Supports orientation (red/black/auto) and last-move highlight toggle.
+ */
+
+declare class CheckersBoardComponent extends EmbedBoardBase {
     showAfkWarning: boolean;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+    showLastMove: boolean;
+    orientation: 'red' | 'black' | 'auto';
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
 
-declare class Connect4BoardComponent implements AfterViewInit {
-    serverUrl: string;
+/**
+ * @description Connect 4 board embed component.
+ */
+
+declare class Connect4BoardComponent extends EmbedBoardBase {
     showAfkWarning: boolean;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
+
+/**
+ * @description Displays the current score for each player in a Connect 4 session.
+ * Reads from `gameState().scores` — styled entirely by the consumer via data attributes.
+ */
 declare class Connect4ScoreComponent {
-    svc: BetaGamerService;
+    private svc;
     get scores(): {
         id: string;
         score: unknown;
     }[];
 }
 
-declare class TictactoeBoardComponent implements AfterViewInit {
-    serverUrl: string;
+/**
+ * @description Tic-tac-toe board embed component.
+ */
+
+declare class TictactoeBoardComponent extends EmbedBoardBase {
     showAfkWarning: boolean;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
 
+/**
+ * @description Subway Runner game embed component.
+ */
+
 declare class SubwayRunnerGameComponent implements AfterViewInit {
     serverUrl: string;
     iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+    protected svc: BetaGamerService;
     get embedUrl(): string;
     ngAfterViewInit(): void;
 }
+
+/**
+ * @description Displays the current score in a Subway Runner session.
+ * Reads from `gameState().score`. Style via `data-role="score"`.
+ */
 declare class SubwayRunnerScoreComponent {
-    svc: BetaGamerService;
+    private svc;
     get score(): any;
 }
+
+/**
+ * @description Displays the remaining lives in a Subway Runner session.
+ * Reads from `gameState().lives`. Style via `data-role="lives"`.
+ */
 declare class SubwayRunnerLivesComponent {
-    svc: BetaGamerService;
+    private svc;
     get lives(): any;
 }
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _socket_io_component_emitter from '@socket.io/component-emitter';
 import * as _angular_core from '@angular/core';
-import { OnDestroy, OnInit, AfterViewInit, ElementRef } from '@angular/core';
+import { OnDestroy, OnInit, AfterViewInit, EventEmitter, ElementRef } from '@angular/core';
 import { Socket } from 'socket.io-client';
 
 type GameType = 'chess' | 'checkers' | 'connect4' | 'tictactoe' | 'subway-runner';
@@ -41,23 +41,55 @@ interface GameState {
 declare class BetaGamerService implements OnDestroy {
     private _socket;
     private _token;
+    /** Decoded session token payload — null until `init()` is called */
     readonly session: _angular_core.WritableSignal<SessionTokenPayload | null>;
+    /** Live game state updated by server events */
     readonly gameState: _angular_core.WritableSignal<GameState>;
     get token(): string;
+    /** The active socket.io connection — available after `init()` with `connectSocket=true` */
     get socket(): Socket<_socket_io_component_emitter.DefaultEventsMap, _socket_io_component_emitter.DefaultEventsMap> | null;
-    init(token: string, serverUrl?: string, socketPath?: string): void;
+    /**
+     * @description Initialises the service with a session token.
+     * Decodes the token, sets up reactive state, and optionally connects the socket.
+     *
+     * @param token - JWT session token from your backend
+     * @param serverUrl - Base URL of the Beta Gamer server
+     * @param socketPath - socket.io path (default `/socket.io`)
+     * @param connectSocket - Set false to skip socket connection (e.g. for SSR or testing)
+     */
+    init(token: string, serverUrl?: string, socketPath?: string, connectSocket?: boolean): void;
     ngOnDestroy(): void;
 }
 
+/**
+ * @description Displays a player's display name and active-turn indicator.
+ * Styled entirely by the consumer via `data-active` and `data-player` attributes.
+ *
+ * @example
+ * <bg-player-card player="self" />
+ * <bg-player-card player="opponent" />
+ */
 declare class PlayerCardComponent {
+    /** Which player to display — `self` = players[0], `opponent` = players[1] */
     player: 'self' | 'opponent';
     private svc;
     get displayName(): string;
     get isActive(): boolean;
 }
 
+/**
+ * @description Live countdown clock that syncs with the server via `game:clock` socket events.
+ * Falls back to a local 1s interval when the game is active.
+ * Renders a `data-low` attribute when under 30 seconds for easy CSS targeting.
+ *
+ * @example
+ * <bg-timer player="self" [initialSeconds]="600" />
+ */
+
 declare class TimerComponent implements OnInit, OnDestroy {
+    /** Which player's clock to display */
     player: 'self' | 'opponent';
+    /** Starting value in seconds (e.g. 600 = 10 min) */
     initialSeconds: number;
     seconds: number;
     private interval;
@@ -67,66 +99,131 @@ declare class TimerComponent implements OnInit, OnDestroy {
     ngOnDestroy(): void;
 }
 
-declare class ChessBoardComponent implements AfterViewInit {
+/**
+ * @description Shared base class for all iframe-based game board components.
+ *
+ * Handles the full iframe lifecycle:
+ * - Injects the session token into the iframe on load via postMessage
+ * - Listens for `bg:leave` messages from the embed and emits `onLeave`
+ * - Cleans up the message listener on destroy
+ *
+ * Subclasses only need to define their embed URL and any game-specific inputs.
+ */
+
+declare abstract class EmbedBoardBase implements AfterViewInit, OnDestroy {
+    /** Base URL of the Beta Gamer server hosting the embed pages */
     serverUrl: string;
-    showAfkWarning: boolean;
+    /** Emitted when the player clicks Leave inside the embed */
+    onLeave: EventEmitter<void>;
     iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
-    get embedUrl(): string;
+    protected svc: BetaGamerService;
+    /** Subclasses return the full embed URL including query params */
+    abstract get embedUrl(): string;
+    private messageHandler;
     ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    /** Builds a query string from a params object, omitting undefined values */
+    protected buildQuery(params: Record<string, string | undefined>): string;
+}
+
+/**
+ * @description Chess board embed component.
+ * Renders the chess game inside an iframe served by the Beta Gamer embed server.
+ * Supports orientation, coordinate display, last-move highlight, and legal move hints.
+ */
+
+declare class ChessBoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
+    showCoords: boolean;
+    showLastMove: boolean;
+    showLegalMoves: boolean;
+    orientation: 'white' | 'black' | 'auto';
+    get embedUrl(): string;
 }
+
+/**
+ * @description Displays the chess move history in algebraic notation.
+ * Styled entirely by the consumer via the `data-role="move-history"` attribute.
+ */
 declare class ChessMoveHistoryComponent {
 }
+
+/**
+ * @description Displays pieces captured by a given player.
+ * Styled entirely by the consumer via the `data-role="captured-pieces"` attribute.
+ */
 declare class ChessCapturedPiecesComponent {
 }
 
-declare class CheckersBoardComponent implements AfterViewInit {
-    serverUrl: string;
+/**
+ * @description Checkers board embed component.
+ * Supports orientation (red/black/auto) and last-move highlight toggle.
+ */
+
+declare class CheckersBoardComponent extends EmbedBoardBase {
     showAfkWarning: boolean;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+    showLastMove: boolean;
+    orientation: 'red' | 'black' | 'auto';
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
 
-declare class Connect4BoardComponent implements AfterViewInit {
-    serverUrl: string;
+/**
+ * @description Connect 4 board embed component.
+ */
+
+declare class Connect4BoardComponent extends EmbedBoardBase {
     showAfkWarning: boolean;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
+
+/**
+ * @description Displays the current score for each player in a Connect 4 session.
+ * Reads from `gameState().scores` — styled entirely by the consumer via data attributes.
+ */
 declare class Connect4ScoreComponent {
-    svc: BetaGamerService;
+    private svc;
     get scores(): {
         id: string;
         score: unknown;
     }[];
 }
 
-declare class TictactoeBoardComponent implements AfterViewInit {
-    serverUrl: string;
+/**
+ * @description Tic-tac-toe board embed component.
+ */
+
+declare class TictactoeBoardComponent extends EmbedBoardBase {
     showAfkWarning: boolean;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
 
+/**
+ * @description Subway Runner game embed component.
+ */
+
 declare class SubwayRunnerGameComponent implements AfterViewInit {
     serverUrl: string;
     iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+    protected svc: BetaGamerService;
     get embedUrl(): string;
     ngAfterViewInit(): void;
 }
+
+/**
+ * @description Displays the current score in a Subway Runner session.
+ * Reads from `gameState().score`. Style via `data-role="score"`.
+ */
 declare class SubwayRunnerScoreComponent {
-    svc: BetaGamerService;
+    private svc;
     get score(): any;
 }
+
+/**
+ * @description Displays the remaining lives in a Subway Runner session.
+ * Reads from `gameState().lives`. Style via `data-role="lives"`.
+ */
 declare class SubwayRunnerLivesComponent {
-    svc: BetaGamerService;
+    private svc;
     get lives(): any;
 }