Hand

Import from @workspace/bridge-react/hand/hand or @workspace/bridge-react/hand/context.

Overview

The Hand module provides a compound component for rendering a single player's hand (13 cards across 4 suits). It supports both display (read-only) and input (editable) modes.

import { Hand } from '@workspace/bridge-react/hand/hand';

const SUITS = ['S', 'H', 'D', 'C'] as const;

Demo

Display Mode

<Hand.Root player="N" cards={cards} readOnly>
  {SUITS.map(suit => (
    <Hand.DisplayRow key={suit} suit={suit} value={cards[suit]} />
  ))}
</Hand.Root>

Input Mode

<Hand.Root player="N" cards={cards} onCardsChange={handleChange}>
  {SUITS.map(suit => (
    <Hand.InputRow key={suit} suit={suit} value={cards[suit]} />
  ))}
</Hand.Root>

Compound API

Hand.Root

The root component provides context to all child components and renders a styled card with a header showing the player name.

Props

Visual States

• Default — yellow background
• Selected (isSelected) — blue background with ring
• Complete — green background (auto-detected from card data)
• Error (hasError) — red background with error messages

Hand.InputRow

Editable suit row with a text input. Uses useBridgeEngine().notation for locale-specific rank parsing (e.g., "RDV" → K, Q, J in French).

Props

Hand.DisplayRow

Read-only suit row that shows a suit icon and formatted ranks as text.

Props

useHandContext

Hook to access the Hand context from within child components.

import { useHandContext } from '@workspace/bridge-react/hand/context';

function CustomRow() {
  const { player, readOnly, isSelected } = useHandContext();
  // ...
}

CompactHand

Compact inline display of a hand — suit symbols followed by ranks. Uses the BridgeEngine context for variant-specific suit colors.

import { CompactHand } from '@workspace/bridge-react/hand/compact-hand';

<CompactHand hand={{ S: "AKQ", H: "97", D: "JT32", C: "654" }} />

Demo

Props

HandsPill

Status pill showing hand validation state (complete, incomplete, or duplicate cards).

import { HandsPill } from '@workspace/bridge-react/hand/hands-pill';

<HandsPill handsStatus={{
  areComplete: false,
  incompletePlayers: ['N', 'S'],
  duplicatedCards: [],
}} />

Demo

Props

HandsActionButtons

Orchestrator component rendering hand manipulation buttons (complete, distribute, redistribute, rotate, clear). Conditionally renders based on hand state.

import { HandsActionButtons } from '@workspace/bridge-react/hand/hands-action-buttons';

<HandsActionButtons
  hands={hands}
  onHandsChange={(updater) => setHands(updater)}
/>

Props

Action Buttons

Individual buttons are also available as direct exports:

Hooks

useHandsStatus

Hook to get the complete status of all hands (completeness, emptiness, too many cards, duplicates).

import { useHandsStatus } from '@workspace/bridge-react/hand/hooks/use-hands-status';

const { areComplete, areEmpty, hasTooManyCards, incompletePlayers, duplicatedCards } = useHandsStatus(hands);

useAreHandsComplete

Hook to check if all hands are complete (have the expected number of cards).

import { useAreHandsComplete } from '@workspace/bridge-react/hand/hooks/use-are-hands-complete';

const { areComplete, incompletePlayers } = useAreHandsComplete(hands);

useHandInputState

Hook for managing hand input state with debouncing and locale-aware formatting. Uses useBridgeEngine().notation internally for parsing and formatting ranks.

Import from @workspace/bridge-react/hand/use-hand-input-state.

Features:

• Internal raw state during typing
• 300ms debounce during typing
• Immediate validation on blur
• Locale-aware display formatting (e.g., "RDV" in French for K, Q, J)
• Duplicate removal

import { useHandInputState } from '@workspace/bridge-react/hand/use-hand-input-state';

const { inputValue, handleChange, handleFocus, handleBlur } = useHandInputState({
  value: ranks,
  onChange: setRanks,
});

<input value={inputValue} onChange={handleChange} onFocus={handleFocus} onBlur={handleBlur} />

Props

Return

useHandInputValidation

Hook for handling validated hand input with debouncing, formatting, and rank filtering. Similar to useHandInputState but additionally filters invalid ranks and sorts by rank order.

Import from @workspace/bridge-react/hand/use-hand-input-validation.

Features:

• 300ms debounce during typing
• Immediate validation on blur
• Locale-aware display formatting
• Filters invalid ranks against engine.notation.validRanks
• Removes duplicates and sorts by rank order

import { useHandInputValidation } from '@workspace/bridge-react/hand/use-hand-input-validation';

const { inputValue, onChange, onFocus, onBlur } = useHandInputValidation({
  value: ranks,
  onValueChange: setRanks,
});

<input value={inputValue} onChange={onChange} onFocus={onFocus} onBlur={onBlur} />

Props

Return