Poker Table UI
Relevant source files
The following files were used as context for generating this wiki page:The Poker Table UI is the central hub for gameplay in the "Hold-em-or-Fold-em-Poker" application. It is responsible for rendering the entire game view, including player video feeds, cards, chips, game state information, and action controls. This component, poker-table.tsx, orchestrates a collection of smaller, specialized components to create a dynamic and interactive poker experience.
The UI is driven by the game state managed within the usePokerGame hook, ensuring that all visual elements are a direct reflection of the underlying game logic from the Poker Engine. The component is rendered after a user proceeds through the Lobby and Game Setup flow.
Sources: components/poker-table.tsx, app/page.tsx:75-78
Component Architecture
The PokerTable component acts as a primary container that assembles various sub-components to build the complete user interface. This compositional approach promotes separation of concerns and reusability.
The following diagram illustrates the high-level component hierarchy:
This diagram shows how PokerTable integrates various child components to construct the game view.
Sources: components/poker-table.tsx:206-368, components/player-position.tsx
Key Sub-components
| Component | Description | Source File |
|---|---|---|
PlayerPosition | Renders a single player at the table, including their video, name, chip count, cards, and turn status. | components/player-position.tsx |
CommunityCards | Displays the community cards (flop, turn, river) in the center of the table. | components/poker-table.tsx:231 |
TurnTimer | A visual timer indicating the remaining time for the current player's turn. | components/poker-table.tsx:261-270 |
DealerButton | A marker indicating which player is the current dealer. | components/poker-table.tsx:228 |
Card | Renders a single playing card, either face-up or face-down. | components/player-position.tsx:90-92 |
GameMenu | A slide-out menu providing access to game options and settings. | components/poker-table.tsx:17-18, 182 |
Game State and Data Flow
The Poker Table UI is entirely state-driven, with the usePokerGame hook serving as the single source of truth for all game-related data. The PokerTable component consumes the gameState object provided by this hook and passes relevant data down to its children as props.
This ensures that the UI automatically updates in response to changes in the game logic, such as a player making a move, cards being dealt, or the pot size changing.
The data flow can be visualized as follows:
This diagram shows that the usePokerGame hook acts as a mediator between the poker-engine and the UI components.
Sources: components/poker-table.tsx:30, hooks/use-poker-game.tsx:11-23
gameState Dependency
The UI heavily relies on properties from the gameState object defined in types/poker.ts.
gameState Property | UI Element | Description |
|---|---|---|
players | PlayerPosition components | Determines each player's name, chip count, bet, and cards. |
communityCards | CommunityCards component | The cards displayed in the center of the table. |
pot | Pot Display | The total amount of chips in the main pot. |
currentPlayerIndex | TurnTimer, PlayerTurnIndicator | Identifies the player whose turn it is, activating their controls and timer. |
dealerSeatNumber | DealerButton | Positions the dealer button at the correct seat. |
phase | Game Phase Display | Shows the current betting round (e.g., "FLOP", "RIVER"). |
gameMode | Action Buttons | Modifies the UI for special game modes like "All-in or Fold". |
Sources: types/poker.ts:49-64, components/poker-table.tsx
Player Representation (PlayerPosition)
Each player at the table is rendered by a PlayerPosition component. It is a composite component responsible for displaying all information related to a specific player.
Sources: components/player-position.tsx
Properties
| Prop | Type | Description |
|---|---|---|
playerId | string | The unique identifier for the player. |
position | string | A string key (e.g., "top-left", "bottom") used to apply CSS classes for positioning. |
showCards | boolean | Determines if the player's hole cards should be rendered. |
Sources: components/player-position.tsx:11-15
Features
- Video Feed: Displays the player's video stream via the
VideoPlayercomponent. - Player Info: Shows the player's name, chip count, and current bet amount. This data is retrieved from the
gameState. - Cards: Renders the player's hole cards using the
Cardcomponent. Cards are face down for opponents. - Turn Indicator: A
PlayerTurnIndicatorcomponent provides a visual cue (a pulsing ring) when it is the player's turn. - Blind Markers: Displays "SB" (Small Blind) or "BB" (Big Blind) markers if the player is in one of those positions for the current hand.
Sources: components/player-position.tsx:55-60, 75-81, 87-93, 99-107
Player Actions and Controls
The main user interaction is handled through a set of action buttons, which are enabled only for the local player during their turn.
Sources: components/poker-table.tsx:286-368
Action Buttons
| Button | Handler Function | Description |
|---|---|---|
| Fold | handleFold | Folds the player's hand. Always available on the player's turn. |
| Check / Call / All-in | handleCall | The label and action are dynamic. It acts as a "Check" if no bet is pending, "Call" to match a bet, or "All-in" if the call amount exceeds the player's stack. |
| Raise | handleRaise | Opens the raise interface or confirms a raise. Disabled if a raise is not a legal move. |
The logic for determining the label of the "Call" button is encapsulated in the getCallButtonLabel function.
Sources: components/poker-table.tsx:112-132
Action Handling Flow
When a user clicks an action button, a sequence of events is triggered, flowing from the UI to the game engine and back.
This diagram shows the flow for a player making a raise action.
Sources: components/poker-table.tsx:112-148, hooks/use-poker-game.tsx:99-110, lib/poker-engine.ts:489-569
"All-in or Fold" Mode
The UI adapts when gameState.gameMode is set to "allin". In this mode:
- The "Raise" button is hidden.
- The "Call" button's logic is modified to perform an "All-in" action.
- The button's label changes to
All-in $${localPlayerChips}.
Sources: components/poker-table.tsx:109, components/poker-table.tsx:117-121, components/poker-table.tsx:308
Turn Management
Visual cues and timers are crucial for managing the flow of the game and ensuring players are aware of their turn.
Turn Timers
- Local Player: A prominent
TurnTimercomponent is displayed in the center of the screen when it is the local player's turn. - Opponents: The
PlayerPositioncomponent for the active player displays aPlayerTurnIndicator, which is a visual ring that animates around their video feed.
Both timer components receive their duration from turnDuration in the usePokerGame hook and trigger an onTimeUp callback.
Sources: components/poker-table.tsx:261-270, components/player-position.tsx:55-60, hooks/use-poker-game.tsx:28
Timeout Handling
If a player's turn timer expires, the handleTimeUp function in the usePokerGame hook is executed. This function implements the auto-action logic:
- If there is no bet to call (
amountToCall === 0), the player will automatically check. - If there is a bet to call, the player will automatically fold.
This prevents the game from stalling due to an inactive player.
Sources: hooks/use-poker-game.tsx:121-135
Conclusion
The Poker Table UI is a sophisticated and well-structured React component that serves as the primary interface for the poker game. By leveraging a compositional architecture, a centralized state management hook (usePokerGame), and a clear data flow, it provides a responsive and intuitive user experience. The UI effectively translates the complex state of the poker-engine into a clear and interactive visual representation, with special considerations for different game modes and robust handling of player turns and actions.