@stargazeryan/poker-ui 0.4.3 → 0.6.0

package/README.md

@@ -9,6 +9,7 @@ an optional center slot, and a small set of built-in **game-feel animations**.
 - 🎯 `CardTable` — responsive, scale-to-fit table with ambient felt, a your-turn edge glow, and winner confetti
 - 💺 `Seat` — a neutral seat frame with slots + animated turn/winner states
 - 🪙 `Pot` — an optional pot pill with a count-up animation
+- 🎰 `ChipStack` / `Chip` — an amount broken into a real stack of chips (white 1, red 5, blue 10, green 25, black 100)
 - 🔁 `nextSeatIndex()` — pure helper for "next seat on the ring"
 
 > Formerly `PokerTable`; kept as a back-compat alias for `CardTable`.
@@ -37,6 +38,10 @@ theme CSS:
 
 > Without the `@source` line, the components render unstyled. Adjust the path to
 > wherever your `node_modules` lives.
+>
+> `npm run test:consumer` in this repo packs the package and builds a throwaway
+> app that follows these three lines literally, then asserts the utilities,
+> tokens and keyframes all made it into the output CSS.
 
 ## Usage
 
@@ -78,15 +83,138 @@ export function Table() {
 
 | Component | Props |
 | --- | --- |
-| `CardTable` | `seatCount` (2–10), `seats` or `renderSeat(i, isYou)`, `yourSeatIndex`, `center`, `ambient` (default true), `yourTurn`, `winnerSeats`, `confetti` (default true), `seatWidth`, `seatHeight` |
-| `Seat` | slots: `header`, `children`, `footer`, `badge`, `overlay`, `above`, `below`, `topLeft`, `topRight`, `topCenter`; states: `isActive`, `isWinner`, `isDimmed`; `animated` (default true), `winnerCrown`, `onClick`, `frameClassName` |
-| `Pot` | `amount`, `label`, `format`, `animate` (count-up, default true) |
+| `CardTable` | `seatCount` (no upper limit), `seats` or `renderSeat(i, isYou, box)`, `bets` or `renderBet(i)` (placed on the betting line toward the center), `betRadiusScale` (default 0.72, and the drawn betting line follows it), `startAngle` (deg of seat 0, default 90° = directly below the center), `yourSeatIndex` (flags `isYou`; no offset), `center`, `ambient` (default true), `yourTurn`, `winnerSeats`, `confetti` (default true), `confettiColors`, `seatWidth`, `seatHeight`, `seatGap` (default 24), `designWidth`, `designHeight`, `marginX`, `marginY`, `feltGap`, `fit`, `className` |
+| `Seat` | slots: `header`, `children`, `footer`, `badge`, `overlay`, `above`, `below`, `topLeft`, `topRight`, `topCenter`; states: `isActive`, `isWinner`, `isDimmed`; `animated` (default true), `winnerCrown`, `onClick`, `frameClassName`, `frameStyle` |
+| `Pot` | `amount`, `label`, `format` (defaults to a plain number), `animate` (count-up, default true) |
+| `ChipStack` | `amount` (chip units), `size`, `denominations`, `maxChips` (default 12), `label`, `className` |
+| `Chip` | `value`, `color`, `colorClassName`, `size`, `label`, `className` |
 | `PlayingCard` | `card` (`"As"`, `"10h"`, `null` = back), `size`: `xs \| sm \| md \| lg` |
-| `HoleCards` | `cards`, `size`, `deal` (staggered deal-in, default true) |
+| `HoleCards` | `cards`, `size`, `deal` (staggered deal-in, default true), `dealKey` (change it to replay the deal for an unchanged hand) |
+| `CardBack` | `size`, `className` |
 | `CommunityCards` | `cards`, `size`, `animated` (3D flip, default true), `slots` (fixed slot count) |
 
-Also exported: `nextSeatIndex`, `cn`, `formatBB`, `BB`, `parseCard`,
-`getSuitSymbol`, and the types `SeatProps`, `CardTableProps`, `PotProps`, `CardSize`.
+Everything the components do is also available as a pure function, one module per
+concern:
+
+| Module | Exports |
+| --- | --- |
+| `geometry` | `seatAngle`, `ellipsePoint`, `ringPoints` |
+| `layout` | `layoutSeats`, `fitSeatScale`, `minSeatSeparation`, `seatPoint`, `tableRadii`, `seatRingRadii`, `ellipseBox`, `SEAT_SHRINK_FLOOR`, `RIM_GAP`, `GLOW_GAP`, `DESIGN_W`, `DESIGN_H`, `DEFAULT_MARGIN_X`, `DEFAULT_MARGIN_Y`, `DEFAULT_FELT_GAP`, `DEFAULT_BET_SCALE`, `DEFAULT_SEAT_GAP`, `DEFAULT_SEAT_W`, `DEFAULT_SEAT_H` |
+| `cards` | `parseCard`, `describeCard`, `getRankName`, `getSuitName`, `getSuitSymbol`, `isRedSuit`, `isKnownSuit` |
+| `chips` | `chipBreakdown`, `chipsTotal`, `chipCount`, `chipSpotColor`, `DEFAULT_DENOMINATIONS` |
+| `color` | `parseColor`, `relativeLuminance`, `flatten`, `contrastRatio`, `mostVisible` |
+| `sizes` | `SIZES` |
+| `motion` | `COUNT_UP_MS`, `DEAL_STAGGER_MS`, `FLIP_STAGGER_MS` |
+| misc | `cn`, `nextSeatIndex`, `formatBB`, `BB` |
+
+Types: `SeatProps`, `CardTableProps`, `SeatBox`, `PotProps`, `PlayingCardProps`,
+`CardBackProps`, `HoleCardsProps`, `CommunityCardsProps`, `ChipProps`,
+`ChipStackProps`, `CardSize`, `ChipSize`, `Size`, `Point`, `Layout`,
+`LayoutOptions`, `SeatLayout`, `EllipseBox`, `Rgba`, `ParsedCard`,
+`Denomination`, `ChipStackEntry`.
+
+### Amounts and units
+
+Nothing here attaches a unit for you. `Pot` renders a plain, locale-grouped
+number and `ChipStack` breaks an amount into chips; neither decides that your
+numbers are big blinds, dollars or points, because that is a game rule and this
+is generic UI.
+
+`formatBB(amount, bb)` is an opt-in poker helper. Pass the big blind — the
+exported `BB = 20` is that helper's own default, not something a component
+applies behind your back:
+
+```tsx
+<Pot amount={1234} />                                  {/* 1,234      */}
+<Pot amount={1234} format={formatBB} />                {/* 61.7 BB    */}
+<Pot amount={1234} format={(n) => formatBB(n, 100)} /> {/* 12.3 BB    */}
+```
+
+### Chips
+
+`ChipStack` turns an amount into a stack of chips, using the greedy breakdown a
+dealer would use: **white 1, red 5, blue 10, green 25, black 100**. Blue is the
+one that varies between houses — plenty of rooms use 20 — so pass
+`denominations` to change the set (and to give the faces dollar labels).
+
+Amounts are in **chip units** (the smallest chip is 1), not big blinds.
+`chipBreakdown` is exported on its own if you want the split without the artwork,
+and anything below the smallest chip is reported by `chipsTotal` rather than
+rounded up. `maxChips` (default 12) keeps a large bet from becoming a hundred
+black chips.
+
+### Ellipse layout
+
+The table, the seat ring and the betting line are all one parametric ellipse:
+
+```
+x(θ) = cx + rx·cos θ      y(θ) = cy + ry·sin θ        θ = startAngle + i·(360/n)
+```
+
+Screen coordinates (y grows downward), so θ = 90° is **directly below** the
+center. **Seat 0 sits at `startAngle` (default 90°)**, and seats divide 360°
+evenly, so 2–10 players always spread out. The betting line uses the same
+formula with a smaller radius (`betRadiusScale`). To keep "you" at the bottom,
+reorder your seat array so the viewer is index 0 (the package adds no offset).
+
+```tsx
+import { seatAngle, ellipsePoint, ringPoints } from "@stargazeryan/poker-ui";
+
+seatAngle(0, 6);                        // 90   (below the center)
+seatAngle(3, 6);                        // 270  (above the center)
+ellipsePoint(300, 200, 120, 80, 90);    // { x: 300, y: 280 }
+ringPoints(4, 300, 200, 120, 80);       // 4 points, first directly below
+```
+
+### Layout, seat size and responsiveness
+
+Everything is laid out in a fixed **design box** (1200×900 by default) which is
+then scaled to fit the container.
+
+| Prop | Default | Meaning |
+| --- | --- | --- |
+| `designWidth` / `designHeight` | `1200` / `900` | the design box |
+| `marginX` / `marginY` | `164/1200`, `196/900` | rail inset, as a **fraction** of the design box |
+| `feltGap` | `11` | felt inset from the rail, design-space px |
+| `seatWidth` / `seatHeight` | `160` / `176` | **preferred** seat frame size |
+| `seatGap` | `24` | minimum clearance between neighbouring frames |
+| `fit` | `"design"` | `"container"` derives the width from the container |
+
+Margins are proportional, so a custom design box stays in proportion, and the
+seat ring is clamped so frames are never clipped by the design box.
+
+Two things to know:
+
+- **`fit="container"` removes letterboxing.** With the default fit, a
+  phone-portrait container (e.g. 390×700) scales the 4:3 design box down and
+  wastes ~58% of the box — the table ends up tiny. `fit="container"` derives the
+  design width from the container's aspect ratio (clamped to 0.5–2.5) so the
+  table fills the box and the seats render much larger.
+- **Seats shrink to keep their distance.** At 160×176, a 6-seat ring leaves
+  161px between neighbours but a 10-seat ring only 25.6px. `CardTable` measures
+  the ring and shrinks the frames uniformly (never below 50%) until `seatGap` is
+  honoured, so 9–10 seat tables never crowd. Every `Seat` inside the table is
+  told the laid-out size through context, so this works whether you pass
+  `renderSeat` or a `seats` array; `renderSeat` also receives the box as its third
+  argument if you want it. The same mechanism is why 11–16 seats lay out at all
+  (measured: 11 → 126×139 frames, 16 → 80×88); past roughly 16 the frames sit on
+  the 50% floor and overlap, so `seatCount` is not clamped above but it is not
+  magic either:
+
+  ```tsx
+  <CardTable
+    seatCount={10}
+    seatGap={48}   // roomier; 0 disables the auto-shrink
+    renderSeat={(i, isYou, box) => (
+      <Seat width={box.width} height={box.height} header={<b>{i}</b>}>
+        <HoleCards cards={hands[i]} size="sm" />
+      </Seat>
+    )}
+  />
+  ```
+
+  `seatGap={0}` disables it; the `seats` array form is not auto-shrunk (pass
+  matching `width`/`height` to your `Seat`s).
 
 ### Sizes
 
@@ -108,7 +236,12 @@ Built-in game-feel (all **on by default**, each toggleable):
 | Your-turn edge glow | `CardTable` | omit `yourTurn` |
 | Winner confetti | `CardTable` | `confetti={false}` |
 
-All animations are disabled automatically when the user prefers reduced motion.
+All CSS animations are disabled automatically when the user prefers reduced
+motion. (The `Pot` count-up is a `requestAnimationFrame` loop, so it is *not*
+covered by that media query.)
+
+Animation tokens live in `@theme`, so Tailwind only ships the keyframes your app
+actually uses.
 
 ## "Whose turn is next?"
 
@@ -123,23 +256,83 @@ const next = nextSeatIndex(current, seatCount, { skip: (i) => players[i].out });
 
 ## Theming
 
-Override the tokens in your own `@theme` block, or pass `className` / `frameClassName`:
+Override any token in your own `@theme` block. Every token below is referenced
+by the components, so an override actually restyles them:
 
 ```css
 @theme {
   --color-felt: #0b3d2e;
-  --color-gold: #ffcc33;
+  --color-felt-light: #14563a;
+  --color-felt-dark: #062418;
+
+  --color-rail: #7a5230;
+  --color-rail-dark: #4d3119;
+  --color-rail-deep: #28190c;
+
+  --color-gold: #ffcc33;       /* turn/winner glow, pot, focus ring */
+  --color-gold-light: #ffe08a; /* ambient glow, backdrop */
+  --color-gold-glow: #fff0c2;  /* spotlight */
+
+  --color-card-back: #14315a;
+  --color-card-back-light: #1e4577;
+  --color-card-back-dark: #0b1d36;
+  --color-card-back-ink: #9fc0e8;
+  --color-card-back-emblem: #ffd98a;
+
+  --color-chip-blue: #1d4ed8;  /* chip denominations */
 }
 ```
 
-## Demo
+Confetti has its own `confettiColors` prop rather than a token, because the
+colours go into inline styles that Tailwind's tree-shaking cannot see.
+
+`--color-chip-red|blue|green|black|white` is the chip palette, used by `Chip`
+and `ChipStack` through `fill-*` utilities. Note that Tailwind v4 only emits a
+theme variable that something references, which is why the package ships no
+unused tokens: every one in `styles.css` is drawn with by a component, so
+overriding any of them works.
+
+Individual components also take `className` / `frameClassName`.
+
+The [docs site](demo/) has a live token editor that sets these custom properties
+on a wrapper, which is exactly what an override does document-wide.
+
+## Docs site
+
+The docs in `demo/` are the library's main documentation: a per-component site
+with live demos, expandable source, API tables and a live token editor, plus a
+[Known gaps](demo/src/docs/pages/guide.tsx) page listing what this library does
+*not* do yet.
+
+```bash
+npm run docs          # dev server (imports ../../src, HMR)
+npm run docs:build    # builds the package, then the docs against dist/
+```
+
+`docs:build` compiles the package first and then builds the site against
+`dist/index.js` rather than `src`, so the deployed site is running the artefact
+consumers actually get. It imports the package by its published name in both
+modes — never a relative path into `src`.
+
+Tests cover the docs too: `tests/docs.test.tsx` renders every route and fails if
+a page throws, and `tests/docs-api.test.ts` reads the real interfaces with the
+TypeScript compiler and fails if an API table drifts from the code.
+
+## Development
 
 ```bash
 npm install --include=dev
-npm run demo        # Vite dev server
-npm run demo:build  # static build
+
+npm run typecheck     # tsc --noEmit
+npm test              # vitest: unit, component, docs routes, docs-vs-types
+npm run build         # tsup -> dist (ESM + CJS + d.ts)
+
+npm run test:consumer # pack + install + build a real consumer app, assert the CSS
 ```
 
+`npm run demo` and `npm run demo:build` remain as aliases for `docs` and
+`docs:build`.
+
 ## License
 
 MIT © 2026 Ryan