poker-irongrid 1.2.1 → 1.4.0

package/README.md

@@ -85,6 +85,8 @@ npm install poker-irongrid
 | `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` | Show hero's live equity against the hands on the grid (requires hero cards) |
+| `equityColors` | `boolean` | `true` | With `evaluator`, color villain hands by hero's equity against each combo: equal-width bands, one per color (`colors[0]` = hero's lowest equity). Hands you color yourself keep their color |
+| `subgrid` | `boolean` | `false` | Split the grid into 3x3 blocks (A–T, 9–6, 5–2) with space after the T and 6 rows/columns; spacing set by `--irongrid-subgrid-gap` (default `6px`) |
 | `preflopTableUrl` | `string \| null` | `null` | URL of poker-bitvaljs's `bench/preflop-table.bin` for exact preflop equity (Monte Carlo without it) |
 
 #### Initial State Props
@@ -221,7 +223,11 @@ When `evaluator={true}`, hero's equity is calculated live (asynchronously) whene
 board, dead cards or the hands on the grid change; there is no button to press.
 - The summary shows hero vs. villain equity against every selected or colored combo
 - The color buttons' **Eq** mode shows hero's equity against each color's hands
-- Both come from one poker-bitvaljs `compareRangeHands` call: exact on the flop, turn and river
+- With `equityColors` (default), the villain hands are colored by hero's equity against each combo, in
+  one equal-width band per color (6 colors: 0–16.7%, 16.7–33.3%, … 83.3–100%, `colors[0]` lowest), so the
+  color buttons show each band's count, share and equity. Hands you color yourself keep their color; band
+  colors follow the selection and go away without hero cards
+- All of it comes from one poker-bitvaljs `compareRangeHands` call: exact on the flop, turn and river
   (a few ms), Monte Carlo preflop and on 1-2 card boards
 - Pass `preflopTableUrl` for exact, near-instant preflop equity (the table is ~1.1 MB, fetched once):
 

package/dist/poker-grid/PokerGridManager.d.ts

@@ -244,22 +244,43 @@ export class PokerGridManager {
     /**
      * Hero's equity against the villain hands on the grid, overall and per color, from one
      * poker-bitvaljs compareRangeHands call (each villain combo's result against hero's hand).
-     * Villain hands are the combos that are selected or colored; hands holding a dead, board or
-     * hero card are left out.
+     * Villain hands are the combos that are selected or colored by hand (colors in `autoColors`, set by
+     * applyEquityBands, don't count); hands holding a dead, board or hero card are left out.
      * @param {Object} hands - Hands object
      * @param {string[]} heroCards - Hero cards (two)
      * @param {string[]} boardCards - Board cards (0-5)
      * @param {string[]} deadCards - Dead cards (may include hero and board cards)
      * @param {string[]} colors - Colors array
-     * @returns {Promise<{hero: number|null, villain: number|null, combos: number, byColor: Object}|null>}
-     *   Equities in percent (null when hero meets no villain combo); null without two hero cards.
+     * @param {Map<string, string>|null} autoColors - Colors applyEquityBands set (combo -> color)
+     * @returns {Promise<{hero: number|null, villain: number|null, combos: number, byColor: Object, byCombo: Object}|null>}
+     *   Equities in percent (null when hero meets no villain combo); byCombo is hero's equity against each
+     *   villain combo. Null without two hero cards.
      */
-    calculateEquity(hands?: any, heroCards?: string[], boardCards?: string[], deadCards?: string[], colors?: string[]): Promise<{
+    calculateEquity(hands?: any, heroCards?: string[], boardCards?: string[], deadCards?: string[], colors?: string[], autoColors?: Map<string, string> | null): Promise<{
         hero: number | null;
         villain: number | null;
         combos: number;
         byColor: any;
+        byCombo: any;
     } | null>;
+    /**
+     * Color villain combos by hero's equity against them: one equal-width band per color, colors[0] for
+     * hero's lowest equity (villain's strongest hands) up to the last color for hero's highest. With 6
+     * colors the bands are 0-16.7%, 16.7-33.3%, ... 83.3-100%.
+     * Only combos without a color, or still holding the color this method gave them, are recolored, so
+     * hand-applied colors stay. Colors this method set are removed from combos that are no longer in
+     * `byCombo` (deselected, dead, or no equity).
+     * @param {Object} hands - Hands object
+     * @param {Object} byCombo - Hero's equity (%) against each villain combo, from calculateEquity
+     * @param {string[]} colors - Colors, one per band
+     * @param {Map<string, string>} autoColors - Colors set by earlier calls (combo -> color)
+     * @returns {{hands: Object, autoColors: Map<string, string>, changed: boolean}}
+     */
+    applyEquityBands(hands: any, byCombo: any, colors: string[], autoColors?: Map<string, string>): {
+        hands: any;
+        autoColors: Map<string, string>;
+        changed: boolean;
+    };
     /**
      * Hero's equity against each color's hands, rounded (0 when a color has no hands).
      * @returns {Promise<Object>} Color equities object

package/dist/poker-grid/PokerGridManager.js

@@ -654,31 +654,38 @@ export class PokerGridManager {
   /**
    * Hero's equity against the villain hands on the grid, overall and per color, from one
    * poker-bitvaljs compareRangeHands call (each villain combo's result against hero's hand).
-   * Villain hands are the combos that are selected or colored; hands holding a dead, board or
-   * hero card are left out.
+   * Villain hands are the combos that are selected or colored by hand (colors in `autoColors`, set by
+   * applyEquityBands, don't count); hands holding a dead, board or hero card are left out.
    * @param {Object} hands - Hands object
    * @param {string[]} heroCards - Hero cards (two)
    * @param {string[]} boardCards - Board cards (0-5)
    * @param {string[]} deadCards - Dead cards (may include hero and board cards)
    * @param {string[]} colors - Colors array
-   * @returns {Promise<{hero: number|null, villain: number|null, combos: number, byColor: Object}|null>}
-   *   Equities in percent (null when hero meets no villain combo); null without two hero cards.
+   * @param {Map<string, string>|null} autoColors - Colors applyEquityBands set (combo -> color)
+   * @returns {Promise<{hero: number|null, villain: number|null, combos: number, byColor: Object, byCombo: Object}|null>}
+   *   Equities in percent (null when hero meets no villain combo); byCombo is hero's equity against each
+   *   villain combo. Null without two hero cards.
    */
-  async calculateEquity(hands = this.hands, heroCards = this.heroCards, boardCards = this.boardCards, deadCards = this.deadCards, colors = this.colors) {
+  async calculateEquity(hands = this.hands, heroCards = this.heroCards, boardCards = this.boardCards, deadCards = this.deadCards, colors = this.colors, autoColors = null) {
     if (heroCards?.length !== 2) return null;
     const board = boardCards || [];
     const otherDead = (deadCards || []).filter(card => !heroCards.includes(card) && !board.includes(card));
     const blocked = new Set([...heroCards, ...board, ...otherDead]);
 
+    const colorOf = (h) => (hands[h] || []).find(item => typeof item === 'string' && item.startsWith('hsl('));
+    const coloredByHand = (h) => {
+      const color = colorOf(h);
+      return !!color && !(autoColors && autoColors.get(h) === color);
+    };
     const villainHands = Object.keys(hands || {}).filter(h =>
       isCombo(h) &&
-      (this.hasExplicitColor(hands[h]) || this.isSelected(hands[h])) &&
+      (coloredByHand(h) || this.isSelected(hands[h])) &&
       !blocked.has(h.substring(0, 2)) && !blocked.has(h.substring(2, 4))
     );
 
     const byColor = {};
     (colors || []).forEach(c => { byColor[c] = null; });
-    if (villainHands.length === 0) return { hero: null, villain: null, combos: 0, byColor };
+    if (villainHands.length === 0) return { hero: null, villain: null, combos: 0, byColor, byCombo: {} };
 
     // Preflop, wait for the table if one is loading (otherwise the result would be Monte Carlo)
     if (board.length === 0 && preflopTableLoad) await preflopTableLoad;
@@ -708,12 +715,59 @@ export class PokerGridManager {
     };
 
     const hero = heroEquityAgainst(villainHands);
+    const byCombo = {};
+    villainHands.forEach(h => { byCombo[h] = heroEquityAgainst([h]); });
     (colors || []).forEach(color => {
       const colorHands = villainHands.filter(h => hands[h].includes(color));
       byColor[color] = colorHands.length > 0 ? heroEquityAgainst(colorHands) : null;
     });
 
-    return { hero, villain: hero === null ? null : 100 - hero, combos: villainHands.length, byColor };
+    return { hero, villain: hero === null ? null : 100 - hero, combos: villainHands.length, byColor, byCombo };
+  }
+
+  /**
+   * Color villain combos by hero's equity against them: one equal-width band per color, colors[0] for
+   * hero's lowest equity (villain's strongest hands) up to the last color for hero's highest. With 6
+   * colors the bands are 0-16.7%, 16.7-33.3%, ... 83.3-100%.
+   * Only combos without a color, or still holding the color this method gave them, are recolored, so
+   * hand-applied colors stay. Colors this method set are removed from combos that are no longer in
+   * `byCombo` (deselected, dead, or no equity).
+   * @param {Object} hands - Hands object
+   * @param {Object} byCombo - Hero's equity (%) against each villain combo, from calculateEquity
+   * @param {string[]} colors - Colors, one per band
+   * @param {Map<string, string>} autoColors - Colors set by earlier calls (combo -> color)
+   * @returns {{hands: Object, autoColors: Map<string, string>, changed: boolean}}
+   */
+  applyEquityBands(hands, byCombo, colors, autoColors = new Map()) {
+    const next = new Map();
+    const newHands = { ...hands };
+    let changed = false;
+    const colorOf = (values) => (values || []).find(item => typeof item === 'string' && item.startsWith('hsl('));
+    const setColor = (h, color) => {
+      const kept = (newHands[h] || []).filter(item => !(typeof item === 'string' && item.startsWith('hsl(')));
+      newHands[h] = color ? [...kept, color] : kept;
+      changed = true;
+    };
+
+    if (colors && colors.length > 0) {
+      const bandWidth = 100 / colors.length;
+      Object.entries(byCombo || {}).forEach(([h, equity]) => {
+        if (equity === null || equity === undefined || Number.isNaN(equity)) return;
+        const current = colorOf(newHands[h]);
+        if (current && autoColors.get(h) !== current) return; // colored by hand
+        const color = colors[Math.min(colors.length - 1, Math.floor(equity / bandWidth))];
+        next.set(h, color);
+        if (current !== color) setColor(h, color);
+      });
+    }
+
+    // Combos that lost their equity color (no longer villain hands, or no equity)
+    autoColors.forEach((color, h) => {
+      if (next.has(h) || !newHands[h]) return;
+      if (colorOf(newHands[h]) === color) setColor(h, null);
+    });
+
+    return { hands: changed ? newHands : hands, autoColors: next, changed };
   }
 
   /**

package/dist/poker-grid/components/Grid.svelte

@@ -18,6 +18,42 @@
   export let showTips = false;
   /** Whether to enable double-click details panel. */
   export let enableDetailsPanel = false;
+  /**
+   * Split the grid into 3x3 blocks: extra space after the T and 6 rows/columns (A-T, 9-6, 5-2).
+   * The space is set by the --irongrid-subgrid-gap CSS variable.
+   */
+  export let subgrid = false;
+
+  /** CSS grid line for a row/column index: with subgrid, spacer tracks follow T (index 4) and 6 (index 8). */
+  function gridLine(index, split) {
+    return index + 1 + (split ? (index >= 5 ? 1 : 0) + (index >= 9 ? 1 : 0) : 0);
+  }
+
+  /**
+   * Hairline frame around each 3x3 block (subgrid): inset shadows on the block's edge cells, so cells stay
+   * flush with their neighbours and only the blocks are outlined.
+   */
+  function blockFrame(row, col, split) {
+    if (!split) return '';
+    const shadows = [];
+    if (row === 0 || row === 5 || row === 9) shadows.push(`inset 0 var(--irongrid-border-width) 0 var(--irongrid-color-border)`);
+    if (row === 4 || row === 8 || row === 12) shadows.push(`inset 0 calc(-1 * var(--irongrid-border-width)) 0 var(--irongrid-color-border)`);
+    if (col === 0 || col === 5 || col === 9) shadows.push(`inset var(--irongrid-border-width) 0 0 var(--irongrid-color-border)`);
+    if (col === 4 || col === 8 || col === 12) shadows.push(`inset calc(-1 * var(--irongrid-border-width)) 0 0 var(--irongrid-color-border)`);
+    return shadows.length ? `box-shadow: ${shadows.join(', ')};` : '';
+  }
+
+  /** The grid cell under a point (or null), from the cells' own positions, so it works with any spacing. */
+  function cellAtPoint(gridElement, x, y) {
+    const cells = gridElement.querySelectorAll('[data-row]');
+    for (const cell of cells) {
+      const r = cell.getBoundingClientRect();
+      if (x >= r.left && x < r.right && y >= r.top && y < r.bottom) {
+        return { element: cell, rect: r, row: Number(cell.dataset.row), col: Number(cell.dataset.col) };
+      }
+    }
+    return null;
+  }
 
   let isDragging = false;
   let tooltip = { visible: false, x: 0, y: 0, content: '' };
@@ -187,19 +223,16 @@
   function handleMouseMove(event) {
     if (!isDragging) return;
     const gridElement = event.currentTarget;
-    const rect = gridElement.getBoundingClientRect();
-    const cellSize = rect.width / 13;
     const coords = getEventCoordinates(event);
-    const x = coords.x - rect.left;
-    const y = coords.y - rect.top;
-    const colIndex = Math.floor(x / cellSize);
-    const rowIndex = Math.floor(y / cellSize);
-    if (colIndex < 0 || colIndex >= 13 || rowIndex < 0 || rowIndex >= 13) return;
-    const cellInfo = getCellInfo(rowIndex, colIndex);
-    const cellRect = { left: colIndex * cellSize, top: rowIndex * cellSize, width: cellSize, height: cellSize };
+    const hit = cellAtPoint(gridElement, coords.x, coords.y);
+    if (!hit) return;
+    const cellInfo = getCellInfo(hit.row, hit.col);
+    const cellSize = Math.min(hit.rect.width, hit.rect.height);
     const bufferSize = cellSize * 0.75;
     const bufferOffset = (cellSize - bufferSize) / 2;
-    const inHitZone = (x - cellRect.left) >= bufferOffset && (x - cellRect.left) <= bufferOffset + bufferSize && (y - cellRect.top) >= bufferOffset && (y - cellRect.top) <= bufferOffset + bufferSize;
+    const x = coords.x - hit.rect.left;
+    const y = coords.y - hit.rect.top;
+    const inHitZone = x >= bufferOffset && x <= bufferOffset + bufferSize && y >= bufferOffset && y <= bufferOffset + bufferSize;
     if (!inHitZone) return;
     if (!dragCells.has(cellInfo.hand)) {
       dragCells.add(cellInfo.hand);
@@ -404,7 +437,7 @@
 </script>
 
   <div class="poker-grid-container" role="region" aria-label="Poker hand grid container">
-    <div class="poker-grid" bind:this={gridElement} onmousemove={handleMouseMove} role="application" aria-label="Poker hand selection grid" tabindex={interactive ? 0 : -1} onmouseup={handleMouseUp}>
+    <div class="poker-grid" class:subgrid bind:this={gridElement} onmousemove={handleMouseMove} role="application" aria-label="Poker hand selection grid" tabindex={interactive ? 0 : -1} onmouseup={handleMouseUp}>
     {#each Array(13) as _, rowIndex}
       {#each Array(13) as __, colIndex}
         {@const cellInfo = getCellInfo(rowIndex, colIndex)}
@@ -412,7 +445,9 @@
           <button
             type="button"
             class="grid-cell {isDragging ? 'dragging' : ''} {interactive ? '' : showTips ? 'non-interactive show-tips' : 'non-interactive'}"
-            style="background: {gradients[cellInfo.hand]} !important"
+            style="background: {gradients[cellInfo.hand]} !important; grid-row: {gridLine(rowIndex, subgrid)}; grid-column: {gridLine(colIndex, subgrid)}; {blockFrame(rowIndex, colIndex, subgrid)}"
+            data-row={rowIndex}
+            data-col={colIndex}
             onclick={(e) => handleClick(e, cellInfo)}
             ondblclick={(e) => handleDoubleClick(e, cellInfo)}
             onmousedown={(e) => handleMouseDown(e, cellInfo)}
@@ -425,7 +460,9 @@
         {:else}
           <div
             class="grid-cell non-interactive"
-            style="background: {gradients[cellInfo.hand]} !important"
+            style="background: {gradients[cellInfo.hand]} !important; grid-row: {gridLine(rowIndex, subgrid)}; grid-column: {gridLine(colIndex, subgrid)}; {blockFrame(rowIndex, colIndex, subgrid)}"
+            data-row={rowIndex}
+            data-col={colIndex}
             role="presentation"
             title={cellInfo.display}
           >
@@ -463,6 +500,12 @@
     gap: 0; 
     border: var(--irongrid-border-width) solid var(--irongrid-color-border); 
   }
+  /* 3x3 blocks: spacer tracks after T and 6 (A-T | 9-6 | 5-2) */
+  .poker-grid.subgrid {
+    grid-template-columns: repeat(5, 1fr) var(--irongrid-subgrid-gap, 6px) repeat(4, 1fr) var(--irongrid-subgrid-gap, 6px) repeat(4, 1fr);
+    grid-template-rows: repeat(5, auto) var(--irongrid-subgrid-gap, 6px) repeat(4, auto) var(--irongrid-subgrid-gap, 6px) repeat(4, auto);
+    border: none;
+  }
   .grid-cell { 
     aspect-ratio: 1; 
     display: flex; 

package/dist/poker-grid/components/Grid.svelte.d.ts

@@ -8,6 +8,7 @@ type Grid = SvelteComponent<{
     interactive?: boolean;
     showTips?: boolean;
     enableDetailsPanel?: boolean;
+    subgrid?: boolean;
 }, {
     cellDetails: CustomEvent<any>;
     cellClick: CustomEvent<any>;
@@ -26,6 +27,7 @@ declare const Grid: $$__sveltets_2_IsomorphicComponent<{
     interactive?: boolean;
     showTips?: boolean;
     enableDetailsPanel?: boolean;
+    subgrid?: boolean;
 }, {
     cellDetails: CustomEvent<any>;
     cellClick: CustomEvent<any>;

package/dist/poker-grid/components/PokerGridPanel.svelte

@@ -25,6 +25,8 @@
   export let showSummary = true;
   export let showTips = false;
   export let enableDetailsPanel = false;
+  /** Split the grid into 3x3 blocks (A-T, 9-6, 5-2) with space between them. */
+  export let subgrid = false;
   export let evaluator = false;
   export let defaultColor = 'hsl(0, 0%, 100%)';
   export let defaultSelectedColor = 'hsl(0, 0%, 85%)';
@@ -35,6 +37,11 @@
    * Without it, preflop equity is a Monte Carlo estimate.
    */
   export let preflopTableUrl = null;
+  /**
+   * With `evaluator`, color the villain hands by hero's equity against each combo: one equal-width band per
+   * color (colors[0] = hero's lowest equity). Hands you color yourself keep their color.
+   */
+  export let equityColors = true;
   $: if (evaluator && preflopTableUrl) loadPreflopTable(preflopTableUrl);
   /** Predefined ranges for range selection. Array of {name: string, abbreviation: string} */
   export let ranges = [];
@@ -111,27 +118,49 @@
   let lastEquityKey = '';
 
   $: equityKey = evaluator
-    ? JSON.stringify({ heroCards, boardCards, deadCards, hands: visibleHands, colors })
+    ? JSON.stringify({ heroCards, boardCards, deadCards, hands: visibleHands, colors, equityColors })
     : '';
   $: if (equityKey !== lastEquityKey) {
     lastEquityKey = equityKey;
     scheduleEquity();
   }
 
+  /** Colors set by equity banding (combo -> color), so they can be updated or removed later. */
+  let autoColors = new Map();
+
+  /** Apply (or, with no equity, remove) the equity band colors. */
+  function applyEquityColors(byCombo) {
+    if (!equityColors && autoColors.size === 0) return;
+    const result = manager.applyEquityBands(internalHands, equityColors ? byCombo || {} : {}, colors, autoColors);
+    autoColors = result.autoColors;
+    if (result.changed) {
+      internalHands = result.hands;
+      hands = result.hands;
+      dispatch('selectionChange', { hands: result.hands, visibleHands });
+    }
+  }
+
   function scheduleEquity() {
     clearTimeout(equityTimer);
     const request = ++equityRequest;
     if (!evaluator || heroCards?.length !== 2) {
       equity = null;
       equityPending = false;
+      // Remove the band colors outside this reactive update (as results are applied, after it)
+      equityTimer = setTimeout(() => {
+        if (request === equityRequest) applyEquityColors(null);
+      }, 0);
       return;
     }
     equityPending = true;
     // A short debounce coalesces bursts (typing cards, dragging across the grid)
     equityTimer = setTimeout(async () => {
       try {
-        const result = await manager.calculateEquity(visibleHands, heroCards, boardCards, deadCards, colors);
-        if (request === equityRequest) equity = result;
+        const result = await manager.calculateEquity(visibleHands, heroCards, boardCards, deadCards, colors, autoColors);
+        if (request === equityRequest) {
+          equity = result;
+          applyEquityColors(result?.byCombo);
+        }
       } catch (error) {
         if (request === equityRequest) equity = null;
       } finally {
@@ -265,6 +294,7 @@
       {interactive}
       {showTips}
       {enableDetailsPanel}
+      {subgrid}
       {manager}
       on:selectionChange={handleSelectionChange}
       on:cellDetails={handleCellDetails}
@@ -312,6 +342,7 @@
       on:clearAll={() => {
         internalHands = {};
         hands = {};
+        autoColors = new Map();
       }}
     />
   </div>

package/dist/poker-grid/components/PokerGridPanel.svelte.d.ts

@@ -10,6 +10,7 @@ type PokerGridPanel = SvelteComponent<{
     interactive?: boolean;
     showTips?: boolean;
     enableDetailsPanel?: boolean;
+    subgrid?: boolean;
     evaluator?: boolean;
     visibleHands?: {};
     ranges?: any[];
@@ -18,13 +19,14 @@ type PokerGridPanel = SvelteComponent<{
     showControls?: boolean;
     showSummary?: boolean;
     preflopTableUrl?: any;
+    equityColors?: boolean;
     initialHands?: any;
     initialBoard?: any;
     initialDead?: any;
 }, {
     cellClick: CustomEvent<any>;
-    rangeSelected: CustomEvent<any>;
     selectionChange: CustomEvent<any>;
+    rangeSelected: CustomEvent<any>;
     deadCardsChange: CustomEvent<any>;
 } & {
     [evt: string]: CustomEvent<any>;
@@ -42,6 +44,7 @@ declare const PokerGridPanel: $$__sveltets_2_IsomorphicComponent<{
     interactive?: boolean;
     showTips?: boolean;
     enableDetailsPanel?: boolean;
+    subgrid?: boolean;
     evaluator?: boolean;
     visibleHands?: {};
     ranges?: any[];
@@ -50,13 +53,14 @@ declare const PokerGridPanel: $$__sveltets_2_IsomorphicComponent<{
     showControls?: boolean;
     showSummary?: boolean;
     preflopTableUrl?: any;
+    equityColors?: boolean;
     initialHands?: any;
     initialBoard?: any;
     initialDead?: any;
 }, {
     cellClick: CustomEvent<any>;
-    rangeSelected: CustomEvent<any>;
     selectionChange: CustomEvent<any>;
+    rangeSelected: CustomEvent<any>;
     deadCardsChange: CustomEvent<any>;
 } & {
     [evt: string]: CustomEvent<any>;

package/dist/poker-grid/theme.css

@@ -53,6 +53,7 @@
 
   /* Border Variables */
   --irongrid-border-width: 1px;
+  --irongrid-subgrid-gap: 6px; /* space between the 3x3 blocks with subgrid */
   --irongrid-border-radius-sm: 0.125rem;
   --irongrid-border-radius-md: 0.25rem;
   --irongrid-border-radius-lg: 0.375rem;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "poker-irongrid",
-	"version": "1.2.1",
+	"version": "1.4.0",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/DarraghGeo/poker-irongrid.git"