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

package/src/types.ts

@@ -0,0 +1,217 @@
+// ============================================================================
+// Time Control Types
+// ============================================================================
+
+/**
+ * String notation for time controls
+ * Examples: "5+3" (5 minutes, 3 second increment), "10" (10 minutes, no increment)
+ */
+export type TimeControlString = `${number}+${number}` | `${number}`;
+
+/**
+ * Single period time control configuration
+ * Used for standalone games or the final period of tournament controls
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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()
+ */
+export type ClockStartMode = "delayed" | "immediate" | "manual";
+
+/**
+ * Clock status
+ */
+export type ClockStatus =
+  | "idle"
+  | "delayed"
+  | "running"
+  | "paused"
+  | "finished";
+
+/**
+ * Player color
+ */
+export type ClockColor = "white" | "black";
+
+/**
+ * Time control configuration
+ */
+export 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)
+ */
+export 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
+ */
+export interface NormalizedTimeControl {
+  baseTime: number; // milliseconds
+  increment: number; // milliseconds
+  delay: number; // milliseconds
+  timingMethod: TimingMethod;
+  clockStart: ClockStartMode;
+  whiteTimeOverride?: number; // milliseconds
+  blackTimeOverride?: number; // milliseconds
+  /** Multi-period configuration (present only for multi-period time controls) */
+  periods?: TimeControlPhase[];
+}
+
+// ============================================================================
+// Clock State Types
+// ============================================================================
+
+/**
+ * Clock times state (used for both current and initial times)
+ */
+export interface ClockTimes {
+  white: number; // milliseconds
+  black: number; // milliseconds
+}
+
+/**
+ * Computed clock info
+ */
+export interface ClockInfo {
+  isRunning: boolean;
+  isPaused: boolean;
+  isFinished: boolean;
+  isWhiteActive: boolean;
+  isBlackActive: boolean;
+  hasTimeout: boolean;
+  hasTimeOdds: boolean;
+}
+
+/**
+ * Clock methods
+ */
+export 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
+ */
+export interface UseChessClockReturn {
+  // Time values (milliseconds)
+  times: ClockTimes;
+  initialTimes: ClockTimes;
+
+  // Status
+  status: ClockStatus;
+  activePlayer: ClockColor | null;
+  timeout: ClockColor | null;
+
+  // Configuration
+  timingMethod: TimingMethod;
+
+  // Computed
+  info: ClockInfo;
+
+  currentPeriodIndex: {
+    white: number;
+    black: number;
+  };
+  totalPeriods: number;
+  currentPeriod: {
+    white: TimeControlPhase;
+    black: TimeControlPhase;
+  };
+  periodMoves: {
+    white: number;
+    black: number;
+  };
+
+  // Methods
+  methods: ClockMethods;
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Time format options
+ */
+export type TimeFormat = "auto" | "mm:ss" | "ss.d" | "hh:mm:ss";
+
+/**
+ * Timing method result
+ */
+export interface TimingMethodResult {
+  newTime: number; // milliseconds
+  delayRemaining: number; // milliseconds (for delay methods)
+}

package/src/utils/__tests__/calculateSwitchTime.test.ts

@@ -0,0 +1,150 @@
+import { calculateSwitchTime } from "../calculateSwitchTime";
+
+describe("calculateSwitchTime", () => {
+  const baseConfig = {
+    baseTime: 300_000,
+    increment: 3_000,
+    delay: 5_000,
+    timingMethod: "fischer" as const,
+    clockStart: "delayed" as const,
+  };
+
+  describe("Fischer timing method", () => {
+    it("should decrement time spent and add increment", () => {
+      const result = calculateSwitchTime(
+        300_000, // currentTime
+        5_000, // timeSpent
+        { ...baseConfig, timingMethod: "fischer", increment: 3_000 },
+      );
+      expect(result).toBe(298_000); // 300000 - 5000 + 3000
+    });
+
+    it("should handle time spent less than increment", () => {
+      const result = calculateSwitchTime(300_000, 2_000, {
+        ...baseConfig,
+        timingMethod: "fischer",
+        increment: 5_000,
+      });
+      expect(result).toBe(303_000); // 300000 - 2000 + 5000
+    });
+
+    it("should handle zero increment", () => {
+      const result = calculateSwitchTime(300_000, 5_000, {
+        ...baseConfig,
+        timingMethod: "fischer",
+        increment: 0,
+      });
+      expect(result).toBe(295_000); // 300000 - 5000
+    });
+
+    it("should not go below zero before increment", () => {
+      const result = calculateSwitchTime(1_000, 5_000, {
+        ...baseConfig,
+        timingMethod: "fischer",
+        increment: 3_000,
+      });
+      expect(result).toBe(3_000); // max(0, 1000 - 5000) + 3000
+    });
+
+    it("should handle increment on very low time", () => {
+      const result = calculateSwitchTime(100, 5_000, {
+        ...baseConfig,
+        timingMethod: "fischer",
+        increment: 3_000,
+      });
+      expect(result).toBe(3_000); // max(0, 100 - 5000) + 3000 = 0 + 3000
+    });
+  });
+
+  describe("Delay timing method", () => {
+    it("should not decrement when within delay period", () => {
+      const result = calculateSwitchTime(
+        300_000,
+        3_000, // within 5 second delay
+        { ...baseConfig, timingMethod: "delay", delay: 5_000 },
+      );
+      expect(result).toBe(300_000); // No decrement (3s - 5s delay = 0 effective)
+    });
+
+    it("should decrement only time spent after delay", () => {
+      const result = calculateSwitchTime(
+        300_000,
+        10_000, // 10 seconds spent, 5 second delay
+        { ...baseConfig, timingMethod: "delay", delay: 5_000 },
+      );
+      expect(result).toBe(295_000); // 300000 - (10000 - 5000) = 295000
+    });
+
+    it("should handle exactly at delay boundary", () => {
+      const result = calculateSwitchTime(
+        300_000,
+        5_000, // exactly delay amount
+        { ...baseConfig, timingMethod: "delay", delay: 5_000 },
+      );
+      expect(result).toBe(300_000); // max(0, 5000 - 5000) = 0 effective
+    });
+
+    it("should handle zero delay", () => {
+      const result = calculateSwitchTime(300_000, 5_000, {
+        ...baseConfig,
+        timingMethod: "delay",
+        delay: 0,
+      });
+      expect(result).toBe(295_000); // 300000 - 5000
+    });
+  });
+
+  describe("Bronstein timing method", () => {
+    it("should decrement and add back time spent within delay", () => {
+      const result = calculateSwitchTime(
+        300_000,
+        3_000, // 3 seconds spent, 5 second delay
+        { ...baseConfig, timingMethod: "bronstein", delay: 5_000 },
+      );
+      expect(result).toBe(300_000); // 300000 - 3000 + 3000 = 300000
+    });
+
+    it("should add back only delay amount when over delay", () => {
+      const result = calculateSwitchTime(
+        300_000,
+        10_000, // 10 seconds spent, 5 second delay
+        { ...baseConfig, timingMethod: "bronstein", delay: 5_000 },
+      );
+      expect(result).toBe(295_000); // 300000 - 10000 + 5000 = 295000
+    });
+
+    it("should handle zero delay", () => {
+      const result = calculateSwitchTime(300_000, 5_000, {
+        ...baseConfig,
+        timingMethod: "bronstein",
+        delay: 0,
+      });
+      expect(result).toBe(295_000); // 300000 - 5000 + 0 = 295000
+    });
+  });
+
+  describe("Edge cases", () => {
+    it("should handle zero time spent", () => {
+      const result = calculateSwitchTime(300_000, 0, baseConfig);
+      expect(result).toBe(303_000); // 300000 - 0 + 3000 (increment)
+    });
+
+    it("should handle very low current time", () => {
+      const result = calculateSwitchTime(500, 3_000, {
+        ...baseConfig,
+        timingMethod: "fischer",
+        increment: 2_000,
+      });
+      expect(result).toBe(2_000); // max(0, 500 - 3000) + 2000 = 0 + 2000
+    });
+
+    it("should handle zero current time", () => {
+      const result = calculateSwitchTime(0, 3_000, {
+        ...baseConfig,
+        timingMethod: "fischer",
+        increment: 2_000,
+      });
+      expect(result).toBe(2_000); // max(0, 0 - 3000) + 2000 = 0 + 2000
+    });
+  });
+});

package/src/utils/__tests__/formatTime.test.ts

@@ -0,0 +1,83 @@
+import { formatClockTime } from "../formatTime";
+
+describe("formatClockTime", () => {
+  describe("auto format", () => {
+    it("should show mm:ss for times >= 20 seconds", () => {
+      expect(formatClockTime(20_000, "auto")).toBe("0:20");
+      expect(formatClockTime(60_000, "auto")).toBe("1:00");
+      expect(formatClockTime(300_000, "auto")).toBe("5:00");
+      expect(formatClockTime(600_000, "auto")).toBe("10:00");
+    });
+
+    it("should show ss.d (seconds with decimal) for times < 20 seconds", () => {
+      expect(formatClockTime(19_999, "auto")).toBe("20.0");
+      expect(formatClockTime(10_500, "auto")).toBe("10.5");
+      expect(formatClockTime(5_000, "auto")).toBe("5.0");
+      expect(formatClockTime(500, "auto")).toBe("0.5");
+      expect(formatClockTime(100, "auto")).toBe("0.1");
+    });
+  });
+
+  describe("mm:ss format", () => {
+    it("should format time as minutes:seconds", () => {
+      expect(formatClockTime(0, "mm:ss")).toBe("0:00");
+      expect(formatClockTime(5_000, "mm:ss")).toBe("0:05");
+      expect(formatClockTime(60_000, "mm:ss")).toBe("1:00");
+      expect(formatClockTime(65_000, "mm:ss")).toBe("1:05");
+      expect(formatClockTime(300_000, "mm:ss")).toBe("5:00");
+      expect(formatClockTime(365_000, "mm:ss")).toBe("6:05");
+    });
+
+    it("should show hours when time exceeds 60 minutes", () => {
+      expect(formatClockTime(3_600_000, "mm:ss")).toBe("1:00:00");
+      expect(formatClockTime(3_665_000, "mm:ss")).toBe("1:01:05");
+      expect(formatClockTime(5_400_000, "mm:ss")).toBe("1:30:00");
+      expect(formatClockTime(7_200_000, "mm:ss")).toBe("2:00:00");
+    });
+  });
+
+  describe("ss.d format", () => {
+    it("should format time as seconds with decimal", () => {
+      expect(formatClockTime(0, "ss.d")).toBe("0.0");
+      expect(formatClockTime(500, "ss.d")).toBe("0.5");
+      expect(formatClockTime(5_000, "ss.d")).toBe("5.0");
+      expect(formatClockTime(10_500, "ss.d")).toBe("10.5");
+      expect(formatClockTime(60_000, "ss.d")).toBe("60.0");
+      expect(formatClockTime(125_500, "ss.d")).toBe("125.5");
+    });
+  });
+
+  describe("hh:mm:ss format", () => {
+    it("should format time as hours:minutes:seconds", () => {
+      expect(formatClockTime(0, "hh:mm:ss")).toBe("0:00:00");
+      expect(formatClockTime(5_000, "hh:mm:ss")).toBe("0:00:05");
+      expect(formatClockTime(65_000, "hh:mm:ss")).toBe("0:01:05");
+      expect(formatClockTime(3_600_000, "hh:mm:ss")).toBe("1:00:00");
+      expect(formatClockTime(3_665_000, "hh:mm:ss")).toBe("1:01:05");
+      expect(formatClockTime(5_400_000, "hh:mm:ss")).toBe("1:30:00");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should clamp negative times to zero", () => {
+      expect(formatClockTime(-1000, "auto")).toBe("0.0");
+      expect(formatClockTime(-1000, "mm:ss")).toBe("0:00");
+    });
+
+    it("should handle zero time", () => {
+      expect(formatClockTime(0, "auto")).toBe("0.0");
+      expect(formatClockTime(0, "mm:ss")).toBe("0:00");
+      expect(formatClockTime(0, "ss.d")).toBe("0.0");
+      expect(formatClockTime(0, "hh:mm:ss")).toBe("0:00:00");
+    });
+
+    it("should ceil to nearest second for mm:ss and hh:mm:ss", () => {
+      // 5999ms should round up to 6 seconds
+      expect(formatClockTime(5_999, "mm:ss")).toBe("0:06");
+      expect(formatClockTime(5_999, "hh:mm:ss")).toBe("0:00:06");
+
+      // 5001ms should round up
+      expect(formatClockTime(5_001, "mm:ss")).toBe("0:06");
+    });
+  });
+});