Poker Grid Component

A comprehensive Svelte 5 component for visualizing and managing poker hand ranges with an interactive 13x13 grid interface.

Installation

npm install poker-irongrid

Peer Dependencies

• svelte: ^5.0.0
• poker-bitvaljs: ^1.0.1 (for equity evaluation)
• poker-extval: ^3.2.0 (for hand evaluation)
• poker-rangeman: ^3.3.2 (for range parsing and filtering)

Quick Start

<script>
  import PokerGridPanel from 'poker-irongrid';
  
  let hands = {};
  let visibleHands = {};
  let deadCards = [];
  let boardCards = [];
  let heroCards = [];
  
  const ranges = [
    { name: 'Tight', abbreviation: '22+,A2s+,K9s+,Q9s+,J9s+,T9s,98s,87s,76s,65s,54s,AJo+,KQo' },
    { name: 'Loose', abbreviation: '22+,A2+,K2+,Q2+,J2+,T2+,92+,82+,72+,62+,52+,42+,32+' }
  ];
  
  const colors = [
    'hsl(60, 100%, 70%)',
    'hsl(120, 100%, 70%)',
    'hsl(240, 100%, 85%)'
  ];
</script>

<PokerGridPanel
  bind:hands
  bind:visibleHands
  bind:deadCards
  bind:boardCards
  bind:heroCards
  {ranges}
  {colors}
/>

API Reference

Props

Core Data Props (Two-way Bound)

| Prop | Type | Default | Description | |------|------|---------|-------------| | hands | Object or Array<string> | {} | Raw hands map (combos/abstracts) or array of hand strings. Format: { "AcKd": ["selected", "hsl(60, 100%, 70%)"], "AA": ["selected"] } | | visibleHands | Object | {} | Visible hands after filtering by dead cards (read-only, automatically computed) | | deadCards | Array<string> | [] | Dead cards as two-character codes (e.g., ["Ac", "Kd"]) | | boardCards | Array<string> | [] | Board cards as two-character codes (e.g., ["As", "Kh", "Qc"]) | | heroCards | Array<string> | [] | Hero cards as two-character codes (e.g., ["Ac", "Kd"]) |

Visibility Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | interactive | boolean | true | Whether the panel is interactive (shows inputs/controls and allows grid interaction) | | showDeadInputs | boolean | true | Show dead cards input fields | | showRangeSelect | boolean | true | Show range selection dropdown | | showControls | boolean | true | Show hand selector controls (filters, colors, etc.) | | showSummary | boolean | true | Show selection summary at bottom | | showTips | boolean | false | Show tooltips on click when non-interactive | | enableDetailsPanel | boolean | false | Enable double-click details panel |

Configuration Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | ranges | Array<{name: string, abbreviation: string}> | [] | Predefined ranges for range selection dropdown | | colors | Array<string> | [] | Color palette for highlighting hands (HSL format recommended) | | defaultColor | string | 'hsl(0, 0%, 100%)' | Default background color for uncolored hands | | defaultSelectedColor | string | 'hsl(0, 0%, 85%)' | Default color for selected hands without explicit color | | evaluator | boolean | false | Enable equity evaluation feature (requires hero cards and hands on grid) |

Initial State Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | initialHands | Object | undefined | Initial hands state (only applied if hands is empty) | | initialBoard | Array<string> | undefined | Initial board cards (only applied if boardCards is empty) | | initialDead | Array<string> | undefined | Initial dead cards (only applied if deadCards is empty) |

Events

| Event | Payload | Description | |-------|---------|-------------| | selectionChange | { hands: Object, visibleHands: Object } | Fired when hands selection changes | | rangeSelected | { name: string, hands: Object } | Fired when a range is selected from dropdown | | deadCardsChange | { deadCards: Array<string>, boardCards: Array<string> } | Fired when dead cards or board cards change | | cellClick | { cellInfo: Object } | Fired when a grid cell is clicked (when showTips is true) | | cellDetails | { cellInfo: Object } | Fired when a grid cell is double-clicked (when enableDetailsPanel is true) |

Data Structures

Hand Format

Hands are represented as objects where keys are hand strings and values are arrays of metadata:

{
  "AcKd": ["selected", "hsl(60, 100%, 70%)"],  // Combo with selection and color
  "AA": ["selected"],                          // Abstract hand (all AA combos)
  "AKs": ["hsl(120, 100%, 70%)"]              // Suited hand with color
}

Hand String Formats:

• Combos: "AcKd" (specific cards)
• Pairs: "AA" (pocket pair)
• Suited: "AKs" (suited hand)
• Offsuit: "AKo" (offsuit hand)

Metadata Array Values:

• "selected" - Hand is selected
• "hsl(...)" - HSL color string for highlighting

Card Format

Cards are represented as two-character strings:

• First character: Rank (A, K, Q, J, T, 9, 8, 7, 6, 5, 4, 3, 2)
• Second character: Suit (c = clubs, d = diamonds, h = hearts, s = spades)

Examples: "Ac", "Kd", "Qh", "Js"

Range Format

Ranges are arrays of objects with name and abbreviation properties:

[
  { 
    name: 'Tight', 
    abbreviation: '22+,A2s+,K9s+,Q9s+,J9s+,T9s,98s,87s,76s,65s,54s,AJo+,KQo' 
  }
]

The abbreviation uses standard poker range notation (e.g., 22+ = all pairs, A2s+ = all suited aces, AJo+ = all offsuit aces).

Features

Interactive Grid

• 13x13 Grid: Visual representation of all 169 possible starting hands
• Click Selection: Click cells to select/deselect hands
• Drag Selection: Click and drag to select multiple hands
• Modifier Keys:
  • Ctrl/Cmd + Click: Add to selection
  • Shift + Click: Remove from selection
  • Normal Click: Replace selection

Dead Card Filtering

• Automatically filters out hands containing dead cards
• Supports hero cards, board cards, and additional dead cards
• Real-time filtering as cards are added/removed

Range Selection

• Apply predefined ranges from dropdown
• Ranges use standard poker notation
• Automatically selects all hands in the range

Hand Filtering

The component includes comprehensive filtering options:

Made Hands:

• One Pair
• Two Pair
• Three of a Kind
• Four of a Kind
• Straight
• Flush
• Full House

Draws:

• Straight Draw
• Flush Draw
• Combo Draw
• Backdoor Flush Draw

Card Filters:

• By Rank (A, K, Q, J, T, 9, 8, 7, 6, 5, 4, 3, 2)
• By Suit (Clubs, Diamonds, Hearts, Spades)
• Paired hands
• Suited hands
• Offsuit hands

Selection Actions:

• Clear All
• Inverse Selection
• Unselect All
• Remove Selected

Color Highlighting

• Assign colors to selected hands
• Multiple colors supported
• Visual distinction between colored and uncolored hands
• Color statistics display

Equity Evaluation

When evaluator={true}:

• Calculate hero equity vs. villain range
• Requires: 2 hero cards and hands on grid
• Uses Monte Carlo simulation (10,000 iterations)
• Displays results as percentages
• Progress indicator during evaluation

Responsive Design

• Mobile-friendly layout
• Touch support for drag selection
• Adaptive grid sizing
• Optimized for various screen sizes

Usage Examples

Basic Usage

<script>
  import PokerGridPanel from 'poker-irongrid';
  
  let hands = {};
  let deadCards = [];
  let boardCards = [];
</script>

<PokerGridPanel
  bind:hands
  bind:deadCards
  bind:boardCards
/>

With Ranges

<script>
  import PokerGridPanel from 'poker-irongrid';
  
  const ranges = [
    { name: 'UTG', abbreviation: '22+,A2s+,K9s+,Q9s+,J9s+,T9s,98s,87s,76s,65s,54s,AJo+,KQo' },
    { name: 'Button', abbreviation: '22+,A2+,K2+,Q2+,J2+,T2+,92+,82+,72+,62+,52+,42+,32+' }
  ];
  
  let hands = {};
</script>

<PokerGridPanel
  bind:hands
  {ranges}
  showRangeSelect={true}
/>

With Colors

<script>
  import PokerGridPanel from 'poker-irongrid';
  
  const colors = [
    'hsl(60, 100%, 70%)',   // Yellow
    'hsl(120, 100%, 70%)',  // Green
    'hsl(240, 100%, 85%)',  // Blue
    'hsl(300, 100%, 70%)',  // Magenta
    'hsl(30, 100%, 70%)',   // Orange
    'hsl(0, 100%, 85%)'     // Red
  ];
  
  let hands = {};
</script>

<PokerGridPanel
  bind:hands
  {colors}
  showControls={true}
/>

With Equity Evaluation

<script>
  import PokerGridPanel from 'poker-irongrid';
  
  let hands = {};
  let heroCards = ['Ac', 'Kd'];
  let boardCards = ['As', 'Kh', 'Qc'];
  let deadCards = [];
</script>

<PokerGridPanel
  bind:hands
  bind:heroCards
  bind:boardCards
  bind:deadCards
  evaluator={true}
  showSummary={true}
/>

Read-Only Display

<script>
  import PokerGridPanel from 'poker-irongrid';
  
  const hands = {
    "AA": ["selected"],
    "KK": ["selected"],
    "QQ": ["hsl(60, 100%, 70%)"]
  };
</script>

<PokerGridPanel
  hands={hands}
  interactive={false}
  showTips={true}
/>

Handling Events

<script>
  import PokerGridPanel from 'poker-irongrid';
  
  let hands = {};
  
  function handleSelectionChange(event) {
    console.log('Selection changed:', event.detail.hands);
    // Update your application state
  }
  
  function handleRangeSelected(event) {
    console.log('Range selected:', event.detail.name);
    console.log('Hands:', event.detail.hands);
  }
</script>

<PokerGridPanel
  bind:hands
  on:selectionChange={handleSelectionChange}
  on:rangeSelected={handleRangeSelected}
/>

Styling

The component uses Tailwind CSS classes and CSS custom properties. You can customize the appearance by defining CSS variables:

:root {
  --poker-accent: #dc2626;
  --poker-border: #e5e7eb;
  --poker-border-light: #d1d5db;
  --poker-text-primary: #111827;
  --poker-text-secondary: #6b7280;
  --poker-white: #ffffff;
}

Component Structure

poker-grid/
├── components/
│   ├── Grid.svelte              # Main 13x13 grid display
│   ├── HandSelector.svelte      # Filter and color controls
│   ├── DeadCardsInput.svelte     # Dead cards input fields
│   ├── RangeSelect.svelte        # Range selection dropdown
│   ├── SelectionSummary.svelte   # Summary and evaluation
│   ├── DetailsPanel.svelte       # Cell details panel
│   └── PokerGridPanel.svelte     # Main component
├── utils/
│   ├── constants.js              # Constants (RANKS, SUITS, etc.)
│   └── index.js                  # Utility exports
├── PokerGridManager.js           # Business logic manager
└── index.js                      # Main entry point

Browser Support

• Modern browsers with ES6+ support
• Touch devices (iOS Safari, Chrome Mobile)
• Desktop browsers (Chrome, Firefox, Safari, Edge)

License

[Add your license here]

Contributing

[Add contribution guidelines here]