Table.php

<?php

declare(strict_types=1);

namespace Likewinter\CardDeck;

/**
 * The card table: owns the deck, named hands, and pile for a game session.
 *
 * Table is the single orchestration point for card movement. Games register
 * named hands, draw cards into them, discard back to the pile, and reset
 * for a new round — all through this interface. The underlying Stacks are
 * private; games interact only through Table's behavioral methods.
 *
 * Hands are keyed by string identifiers chosen by the game:
 *   $table->addHand('dealer', new Stack());
 *   $table->addHand('north', new Stack(capacity: 13));
 *   $table->draw('north', 5);
 */
class Table
{
    private Stack $deck;
    private Stack $pile;

    /** @var array<string, Stack> */
    private array $hands = [];

    /**
     * @param Stack $deck The draw pile; the table owns it from here on.
     * @param DrawMode $drawMode How draw()/drawAll() move cards from the deck into hands.
     * @param bool $shuffle Shuffle the deck immediately.
     */
    public function __construct(
        Stack $deck,
        private readonly DrawMode $drawMode = DrawMode::Sequential,
        bool $shuffle = false,
    ) {
        $this->deck = $deck;
        $this->pile = new Stack();
        if ($shuffle) {
            $this->deck->shuffle();
        }
    }

    // ── Hand registry ────────────────────────────────────────────────────

    /**
     * Register a named hand.
     *
     * @throws \InvalidArgumentException If a hand with this name already exists.
     */
    public function addHand(string $name, Stack $hand): void
    {
        if (array_key_exists($name, $this->hands)) {
            throw new \InvalidArgumentException("Hand '{$name}' already exists");
        }
        $this->hands[$name] = $hand;
    }

    /**
     * Remove a named hand, moving its remaining cards to the pile.
     */
    public function removeHand(string $name): void
    {
        $hand = $this->hand($name);
        $hand->moveAllTo($this->pile);
        unset($this->hands[$name]);
    }

    /**
     * Returns the named hand.
     *
     * @throws \InvalidArgumentException If no hand with this name exists.
     */
    public function hand(string $name): Stack
    {
        return $this->hands[$name] ?? throw new \InvalidArgumentException("Hand '{$name}' does not exist");
    }

    /**
     * Whether a hand with this name has been registered.
     */
    public function hasHand(string $name): bool
    {
        return array_key_exists($name, $this->hands);
    }

    /**
     * Names of all registered hands, in registration order.
     *
     * @return list<string>
     */
    public function handNames(): array
    {
        return array_keys($this->hands);
    }

    // ── Drawing ──────────────────────────────────────────────────────────

    /**
     * Draw cards from the deck into a named hand.
     * Respects the table's DrawMode (Random draws random cards).
     *
     * @throws \InvalidArgumentException If the hand does not exist.
     * @throws \LogicException If the deck has fewer than $num cards.
     */
    public function draw(string $name, int $num = 1): void
    {
        $hand = $this->hand($name);

        if ($num > $this->deck->count()) {
            throw new \LogicException('Not enough cards in deck');
        }

        match ($this->drawMode) {
            DrawMode::Random => $this->drawRandomToHand($hand, $num),
            DrawMode::Sequential, DrawMode::OneByOne => $this->deck->moveTo($hand, $num),
        };
    }

    /**
     * Draw $num cards to every registered hand, respecting DrawMode.
     *
     * @throws \LogicException If no hands are registered or the deck cannot cover the full deal.
     */
    public function drawAll(int $num = 1): void
    {
        if ($this->hands === []) {
            throw new \LogicException('No hands registered');
        }

        if (($num * count($this->hands)) > $this->deck->count()) {
            throw new \LogicException('Not enough cards in deck');
        }

        match ($this->drawMode) {
            DrawMode::OneByOne => $this->drawOneByOne($num),
            DrawMode::Sequential => $this->drawSequential($num),
            DrawMode::Random => $this->drawRandomAll($num),
        };
    }

    /**
     * Draw cards into a named hand until it reaches $target cards,
     * or the deck runs out — whichever comes first.
     *
     * Returns the number of cards actually drawn.
     *
     * @throws \InvalidArgumentException If the hand does not exist.
     */
    #[\NoDiscard]
    public function drawUpTo(string $name, int $target): int
    {
        $hand = $this->hand($name);
        $needed = $target - $hand->count();

        if ($needed <= 0) {
            return 0;
        }

        $available = min($needed, $this->deck->count());

        if ($available > 0) {
            $this->draw($name, $available);
        }

        return $available;
    }

    // ── Discarding ───────────────────────────────────────────────────────

    /**
     * Discard specific cards from a named hand to the pile.
     * With no cards argument, discards the entire hand.
     *
     * @throws \InvalidArgumentException If the hand does not exist or does not contain the given cards.
     */
    public function discard(string $name, PlayableCard ...$cards): void
    {
        $hand = $this->hand($name);

        if ($cards === []) {
            $hand->moveAllTo($this->pile);
            return;
        }

        $hand->moveCardsTo($this->pile, ...$cards);
    }

    /**
     * Collect cards from outside the table (e.g., played trick cards)
     * into the pile so reset() can recover them.
     */
    public function collectToPile(PlayableCard ...$cards): void
    {
        $this->pile->addCards(...$cards);
    }

    // ── Lifecycle ────────────────────────────────────────────────────────

    /**
     * Return all cards from hands and the pile to the deck.
     */
    public function reset(): void
    {
        foreach ($this->hands as $hand) {
            $hand->moveAllTo($this->deck);
        }
        $this->pile->moveAllTo($this->deck);
    }

    /**
     * Shuffle the deck. Does not affect hands or the pile.
     */
    public function shuffle(): void
    {
        $this->deck->shuffle();
    }

    // ── Inspection ───────────────────────────────────────────────────────

    /**
     * Number of cards remaining in the deck.
     */
    public function deckCount(): int
    {
        return $this->deck->count();
    }

    /**
     * Number of cards currently in the pile.
     */
    public function pileCount(): int
    {
        return $this->pile->count();
    }

    /**
     * Peek at cards in the deck without removing them.
     *
     * @throws \InvalidArgumentException If the deck has fewer than $num cards.
     */
    #[\NoDiscard]
    public function peekDeck(int $num = 1): Stack
    {
        return $this->deck->peek($num);
    }

    /**
     * Peek at cards from the bottom of the deck without removing them.
     *
     * @throws \InvalidArgumentException If the deck has fewer than $num cards.
     */
    #[\NoDiscard]
    public function peekDeckBottom(int $num = 1): Stack
    {
        return $this->deck->peekBottom($num);
    }

    // ── Private draw strategies ──────────────────────────────────────────

    private function drawOneByOne(int $num): void
    {
        for ($i = 0; $i < $num; $i++) {
            foreach ($this->hands as $hand) {
                $this->deck->moveTo($hand, 1);
            }
        }
    }

    private function drawSequential(int $num): void
    {
        foreach ($this->hands as $hand) {
            $this->deck->moveTo($hand, $num);
        }
    }

    private function drawRandomAll(int $num): void
    {
        for ($i = 0; $i < $num; $i++) {
            foreach ($this->hands as $hand) {
                $this->drawRandomToHand($hand, 1);
            }
        }
    }

    private function drawRandomToHand(Stack $hand, int $num): void
    {
        for ($i = 0; $i < $num; $i++) {
            $this->deck->moveCardsTo($hand, ...$this->deck->peekRandom());
        }
    }
}