@react-chess-tools/react-chess-clock 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,528 @@
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+
+/**
+ * String notation for time controls
+ * Examples: "5+3" (5 minutes, 3 second increment), "10" (10 minutes, no increment)
+ */
+type TimeControlString = `${number}+${number}` | `${number}`;
+/**
+ * Single period time control configuration
+ * Used for standalone games or the final period of tournament controls
+ */
+interface TimeControl {
+    /** Base time in seconds */
+    baseTime: number;
+    /** Increment in seconds (default: 0) */
+    increment?: number;
+    /** Delay in seconds (for delay timing methods) */
+    delay?: number;
+}
+/**
+ * A single time control period for tournament play
+ */
+interface TimeControlPhase extends TimeControl {
+    /** Moves required in this period (undefined = sudden death period) */
+    moves?: number;
+}
+/**
+ * Time control input - accepts string notation, object configuration, or multi-period array
+ */
+type TimeControlInput = TimeControlString | TimeControl | TimeControlPhase[];
+/**
+ * Clock timing method
+ * - "fischer": Standard increment - adds time after each move
+ * - "delay": Simple delay - countdown waits before decrementing
+ * - "bronstein": Bronstein delay - adds back actual time used up to delay amount
+ */
+type TimingMethod = "fischer" | "delay" | "bronstein";
+/**
+ * Clock start behavior
+ * - "delayed": Clock starts after Black's first move (Lichess-style)
+ * - "immediate": White's clock starts immediately (Chess.com-style)
+ * - "manual": Clock starts only when user explicitly calls start()
+ */
+type ClockStartMode = "delayed" | "immediate" | "manual";
+/**
+ * Clock status
+ */
+type ClockStatus = "idle" | "delayed" | "running" | "paused" | "finished";
+/**
+ * Player color
+ */
+type ClockColor = "white" | "black";
+/**
+ * Time control configuration
+ */
+interface TimeControlConfig {
+    /** Time specification (required) */
+    time: TimeControlInput;
+    /** Override starting time for white (seconds) - for time odds */
+    whiteTime?: number;
+    /** Override starting time for black (seconds) - for time odds */
+    blackTime?: number;
+    /** Timing method (default: 'fischer') */
+    timingMethod?: TimingMethod;
+    /** Clock start behavior (default: 'delayed') */
+    clockStart?: ClockStartMode;
+    /** Callback when a player's time runs out */
+    onTimeout?: (loser: ClockColor) => void;
+    /** Callback when active player switches */
+    onSwitch?: (activePlayer: ClockColor) => void;
+    /** Callback on each time update */
+    onTimeUpdate?: (times: {
+        white: number;
+        black: number;
+    }) => void;
+}
+/**
+ * Period tracking state (only used for multi-period controls)
+ */
+interface PeriodState {
+    /** Current period index for each player (0-based) */
+    periodIndex: {
+        white: number;
+        black: number;
+    };
+    /** Moves made in current period by each player */
+    periodMoves: {
+        white: number;
+        black: number;
+    };
+    /** All periods for this time control */
+    periods: TimeControlPhase[];
+}
+/**
+ * Normalized time control with all times converted to milliseconds
+ */
+interface NormalizedTimeControl {
+    baseTime: number;
+    increment: number;
+    delay: number;
+    timingMethod: TimingMethod;
+    clockStart: ClockStartMode;
+    whiteTimeOverride?: number;
+    blackTimeOverride?: number;
+    /** Multi-period configuration (present only for multi-period time controls) */
+    periods?: TimeControlPhase[];
+}
+/**
+ * Clock times state (used for both current and initial times)
+ */
+interface ClockTimes {
+    white: number;
+    black: number;
+}
+/**
+ * Computed clock info
+ */
+interface ClockInfo {
+    isRunning: boolean;
+    isPaused: boolean;
+    isFinished: boolean;
+    isWhiteActive: boolean;
+    isBlackActive: boolean;
+    hasTimeout: boolean;
+    hasTimeOdds: boolean;
+}
+/**
+ * Clock methods
+ */
+interface ClockMethods {
+    start: () => void;
+    pause: () => void;
+    resume: () => void;
+    switch: () => void;
+    reset: (timeControl?: TimeControlInput) => void;
+    addTime: (player: ClockColor, milliseconds: number) => void;
+    setTime: (player: ClockColor, milliseconds: number) => void;
+}
+/**
+ * Complete clock state return type
+ */
+interface UseChessClockReturn {
+    times: ClockTimes;
+    initialTimes: ClockTimes;
+    status: ClockStatus;
+    activePlayer: ClockColor | null;
+    timeout: ClockColor | null;
+    timingMethod: TimingMethod;
+    info: ClockInfo;
+    currentPeriodIndex: {
+        white: number;
+        black: number;
+    };
+    totalPeriods: number;
+    currentPeriod: {
+        white: TimeControlPhase;
+        black: TimeControlPhase;
+    };
+    periodMoves: {
+        white: number;
+        black: number;
+    };
+    methods: ClockMethods;
+}
+/**
+ * Time format options
+ */
+type TimeFormat = "auto" | "mm:ss" | "ss.d" | "hh:mm:ss";
+/**
+ * Timing method result
+ */
+interface TimingMethodResult {
+    newTime: number;
+    delayRemaining: number;
+}
+
+interface ChessClockResetProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
+    asChild?: boolean;
+    children?: ReactNode;
+    onClick?: React__default.MouseEventHandler<HTMLElement>;
+    timeControl?: TimeControlInput;
+}
+/**
+ * ChessClock.Reset - Button to reset the clock
+ *
+ * Supports the asChild pattern and optional new time control on reset.
+ *
+ * @example
+ * ```tsx
+ * <ChessClock.Reset>Reset</ChessClock.Reset>
+ *
+ * // Reset with new time control
+ * <ChessClock.Reset timeControl="10+5">Change to 10+5</ChessClock.Reset>
+ *
+ * // As child
+ * <ChessClock.Reset asChild>
+ *   <div className="custom-reset">Reset</div>
+ * </ChessClock.Reset>
+ * ```
+ */
+declare const Reset: React__default.ForwardRefExoticComponent<ChessClockResetProps & {
+    children?: ReactNode | undefined;
+} & React__default.RefAttributes<HTMLElement>>;
+
+interface ChessClockPlayPauseProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
+    asChild?: boolean;
+    children?: ReactNode;
+    onClick?: React__default.MouseEventHandler<HTMLElement>;
+    /** Content shown when clock is idle (not yet started) - clicking will start the clock */
+    startContent?: ReactNode;
+    /** Content shown when clock is running - clicking will pause */
+    pauseContent?: ReactNode;
+    /** Content shown when clock is paused - clicking will resume */
+    resumeContent?: ReactNode;
+    /** Content shown when clock is in delayed mode - clicking will start the clock immediately */
+    delayedContent?: ReactNode;
+    /** Content shown when clock is finished - button is disabled but shows this content */
+    finishedContent?: ReactNode;
+}
+/**
+ * ChessClock.PlayPause - Button to start, pause, and resume the clock
+ *
+ * Supports the asChild pattern and conditional content based on clock state.
+ * When no children or custom content is provided, sensible defaults are used for each state.
+ *
+ * @example
+ * ```tsx
+ * // With children (backward compatible)
+ * <ChessClock.PlayPause>
+ *   <span>Toggle</span>
+ * </ChessClock.PlayPause>
+ *
+ * // No props - uses defaults for all states
+ * <ChessClock.PlayPause />
+ * // Shows: "Start" → "Pause" → "Resume" → "Game Over"
+ *
+ * // Override just one state, others use defaults
+ * <ChessClock.PlayPause pauseContent="⏸️ Stop" />
+ * // Shows: "Start" → "⏸️ Stop" → "Resume" → "Game Over"
+ *
+ * // As child
+ * <ChessClock.PlayPause asChild>
+ *   <div className="custom-button">Toggle</div>
+ * </ChessClock.PlayPause>
+ * ```
+ */
+declare const PlayPause: React__default.ForwardRefExoticComponent<ChessClockPlayPauseProps & {
+    children?: ReactNode | undefined;
+} & React__default.RefAttributes<HTMLElement>>;
+
+interface ChessClockControlProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
+    asChild?: boolean;
+    children?: ReactNode;
+    onClick?: React__default.MouseEventHandler<HTMLElement>;
+}
+/**
+ * ChessClock.Switch - Button to manually switch the active clock
+ *
+ * Supports the asChild pattern for custom rendering.
+ *
+ * @example
+ * ```tsx
+ * <ChessClock.Switch>Switch Clock</ChessClock.Switch>
+ *
+ * // As child
+ * <ChessClock.Switch asChild>
+ *   <div className="custom-switch">Switch</div>
+ * </ChessClock.Switch>
+ * ```
+ */
+declare const Switch: React__default.ForwardRefExoticComponent<ChessClockControlProps & {
+    children?: ReactNode | undefined;
+} & React__default.RefAttributes<HTMLElement>>;
+
+interface ChessClockDisplayProps extends React__default.HTMLAttributes<HTMLDivElement> {
+    color: ClockColor;
+    format?: "auto" | "mm:ss" | "ss.d" | "hh:mm:ss";
+    formatTime?: (milliseconds: number) => string;
+}
+/**
+ * ChessClock.Display - Displays the current time for a player
+ *
+ * Renders an unstyled div with data attributes for custom styling.
+ *
+ * @example
+ * ```tsx
+ * <ChessClock.Display color="white" format="auto" />
+ * <ChessClock.Display color="black" format="ss.d" />
+ * <ChessClock.Display
+ *   color="white"
+ *   formatTime={(ms) => `${Math.ceil(ms / 1000)}s`}
+ * />
+ * ```
+ */
+declare const Display: React__default.ForwardRefExoticComponent<ChessClockDisplayProps & React__default.RefAttributes<HTMLDivElement>>;
+
+interface ChessClockRootProps {
+    timeControl: TimeControlConfig;
+    children: ReactNode;
+}
+
+/**
+ * ChessClock compound components
+ *
+ * @example
+ * ```tsx
+ * import { ChessClock } from "@react-chess-tools/react-chess-clock";
+ *
+ * function ClockApp() {
+ *   return (
+ *     <ChessClock.Root timeControl={{ time: "5+3" }}>
+ *       <ChessClock.Display color="black" />
+ *       <ChessClock.Display color="white" />
+ *       <ChessClock.Switch>Switch</ChessClock.Switch>
+ *       <ChessClock.PlayPause
+ *         startContent="Start"
+ *         pauseContent="Pause"
+ *         resumeContent="Resume"
+ *       />
+ *       <ChessClock.Reset>Reset</ChessClock.Reset>
+ *     </ChessClock.Root>
+ *   );
+ * }
+ * ```
+ */
+declare const ChessClock: {
+    Root: React.FC<React.PropsWithChildren<ChessClockRootProps>>;
+    Display: React.ForwardRefExoticComponent<ChessClockDisplayProps & React.RefAttributes<HTMLDivElement>>;
+    Switch: React.ForwardRefExoticComponent<ChessClockControlProps & {
+        children?: React.ReactNode | undefined;
+    } & React.RefAttributes<HTMLElement>>;
+    PlayPause: React.ForwardRefExoticComponent<ChessClockPlayPauseProps & {
+        children?: React.ReactNode | undefined;
+    } & React.RefAttributes<HTMLElement>>;
+    Reset: React.ForwardRefExoticComponent<ChessClockResetProps & {
+        children?: React.ReactNode | undefined;
+    } & React.RefAttributes<HTMLElement>>;
+};
+
+/**
+ * Format milliseconds into a display string
+ * @param milliseconds - Time in milliseconds
+ * @param format - Format type
+ * @returns Formatted time string
+ */
+declare function formatClockTime(milliseconds: number, format?: TimeFormat): string;
+
+/**
+ * Main hook for chess clock state management.
+ * Provides timing functionality for chess games with various timing methods.
+ *
+ * For server-authoritative clocks, use `methods.setTime()` to sync server times.
+ * The clock will restart its display interpolation from the new value on each call.
+ *
+ * **Auto-reset behavior:** The clock automatically resets when time-relevant
+ * options change (`time`, `timingMethod`, `clockStart`, `whiteTime`, `blackTime`).
+ * Callbacks (`onTimeout`, `onSwitch`, `onTimeUpdate`) do not trigger a reset
+ * and can be changed without affecting clock state.
+ *
+ * @param options - Clock configuration options
+ * @returns Clock state, info, and methods
+ */
+declare function useChessClock(options: TimeControlConfig): UseChessClockReturn;
+/**
+ * Optional chess clock hook for cases where clock may not be needed
+ * Maintains hook order by always calling the implementation internally
+ *
+ * @param options - Clock configuration options, or undefined to disable
+ * @returns Clock state, info, and methods, or null if disabled
+ */
+declare function useOptionalChessClock(options?: TimeControlConfig): ReturnType<typeof useChessClock> | null;
+
+/**
+ * Context for chess clock state
+ * Provided by ChessClock.Root and consumed by child components
+ */
+declare const ChessClockContext: React.Context<UseChessClockReturn | null>;
+/**
+ * Hook to access chess clock context from child components
+ * Must be used within a ChessClock.Root provider
+ *
+ * @throws Error if used outside of ChessClock.Root
+ * @returns Chess clock state and methods
+ */
+declare function useChessClockContext(): UseChessClockReturn;
+
+/**
+ * Parse a time control string into a TimeControl object
+ * @param input - Time control string (e.g., "5+3", "10")
+ * @returns Parsed time control with baseTime in seconds
+ * @throws Error if input is invalid
+ */
+declare function parseTimeControlString(input: TimeControlString): TimeControl;
+/**
+ * Parse a multi-period time control string into an array of TimeControlPhase
+ * Format: "40/90+30,sd/30+30" or "40/120+30,20/60+30,g/15+30"
+ *
+ * Period format: [moves/]time[+increment] or [SD|G/]time[+increment]
+ * - moves: Number of moves required for this period (e.g., "40" in "40/90+30")
+ * - time: Time in minutes for this period (e.g., "90" in "40/90+30")
+ * - increment: Increment in seconds after each move (e.g., "30" in "40/90+30")
+ * - SD or G prefix: Sudden death period (no moves requirement, overrides any moves prefix)
+ *
+ * @param input - Multi-period time control string
+ * @returns Array of TimeControlPhase with times in seconds
+ * @throws Error if input is invalid
+ *
+ * @example
+ * ```ts
+ * parseMultiPeriodTimeControl("40/90+30,sd/30+30")
+ * // Returns: [
+ * //   { baseTime: 5400, increment: 30, moves: 40 },
+ * //   { baseTime: 1800, increment: 30 }
+ * // ]
+ * ```
+ */
+declare function parseMultiPeriodTimeControl(input: string): TimeControlPhase[];
+/**
+ * Normalize any time control input into a NormalizedTimeControl
+ * @param input - Time control string, object, or array of periods
+ * @param timingMethod - Optional timing method (defaults to "fischer")
+ * @param clockStart - Optional clock start mode (defaults to "delayed")
+ * @returns Normalized time control with times in milliseconds
+ */
+declare function normalizeTimeControl(input: TimeControlInput, timingMethod: NormalizedTimeControl["timingMethod"], clockStart: NormalizedTimeControl["clockStart"]): NormalizedTimeControl;
+/**
+ * Parse complete TimeControlConfig into NormalizedTimeControl
+ * @param config - Time control configuration
+ * @returns Fully normalized time control
+ */
+declare function parseTimeControlConfig(config: TimeControlConfig): NormalizedTimeControl;
+/**
+ * Get initial times from a normalized time control
+ * @param config - Normalized time control
+ * @returns Initial times for white and black in milliseconds
+ */
+declare function getInitialTimes(config: NormalizedTimeControl): {
+    white: number;
+    black: number;
+};
+
+/**
+ * Preset time controls for common chess formats
+ *
+ * @example
+ * ```tsx
+ * import { presets } from "@react-chess-tools/react-chess-clock";
+ *
+ * <ChessClock.Root timeControl={{ time: presets.blitz5_3 }}>
+ *   <ChessClock.Display color="white" />
+ *   <ChessClock.Display color="black" />
+ * </ChessClock.Root>
+ * ```
+ */
+declare const presets: {
+    readonly bullet1_0: {
+        readonly baseTime: 60;
+        readonly increment: 0;
+    };
+    readonly bullet1_1: {
+        readonly baseTime: 60;
+        readonly increment: 1;
+    };
+    readonly bullet2_1: {
+        readonly baseTime: 120;
+        readonly increment: 1;
+    };
+    readonly blitz3_0: {
+        readonly baseTime: 180;
+        readonly increment: 0;
+    };
+    readonly blitz3_2: {
+        readonly baseTime: 180;
+        readonly increment: 2;
+    };
+    readonly blitz5_0: {
+        readonly baseTime: 300;
+        readonly increment: 0;
+    };
+    readonly blitz5_3: {
+        readonly baseTime: 300;
+        readonly increment: 3;
+    };
+    readonly rapid10_0: {
+        readonly baseTime: 600;
+        readonly increment: 0;
+    };
+    readonly rapid10_5: {
+        readonly baseTime: 600;
+        readonly increment: 5;
+    };
+    readonly rapid15_10: {
+        readonly baseTime: 900;
+        readonly increment: 10;
+    };
+    readonly classical30_0: {
+        readonly baseTime: 1800;
+        readonly increment: 0;
+    };
+    readonly classical90_30: {
+        readonly baseTime: 5400;
+        readonly increment: 30;
+    };
+    readonly fideClassical: readonly [{
+        readonly baseTime: 5400;
+        readonly increment: 30;
+        readonly moves: 40;
+    }, {
+        readonly baseTime: 1800;
+        readonly increment: 30;
+        readonly moves: 20;
+    }, {
+        readonly baseTime: 900;
+        readonly increment: 30;
+    }];
+    readonly uscfClassical: readonly [{
+        readonly baseTime: 7200;
+        readonly moves: 40;
+    }, {
+        readonly baseTime: 3600;
+        readonly moves: 20;
+    }, {
+        readonly baseTime: 1800;
+    }];
+};
+
+export { ChessClock, ChessClockContext, type ChessClockControlProps, type ChessClockDisplayProps, type ChessClockPlayPauseProps, type ChessClockResetProps, type ChessClockRootProps, type ClockColor, type ClockInfo, type ClockMethods, type ClockStartMode, type ClockStatus, type ClockTimes, Display, type NormalizedTimeControl, type PeriodState, PlayPause, Reset, Switch, type TimeControl, type TimeControlConfig, type TimeControlInput, type TimeControlPhase, type TimeControlString, type TimeFormat, type TimingMethod, type TimingMethodResult, type UseChessClockReturn, formatClockTime, getInitialTimes, normalizeTimeControl, parseMultiPeriodTimeControl, parseTimeControlConfig, parseTimeControlString, presets, useChessClock, useChessClockContext, useOptionalChessClock };