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

package/src/components/ChessClock/index.ts

@@ -0,0 +1,44 @@
+import { Root } from "./parts/Root";
+import { Display } from "./parts/Display";
+import { Switch } from "./parts/Switch";
+import { PlayPause } from "./parts/PlayPause";
+import { Reset } from "./parts/Reset";
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+export const ChessClock = {
+  Root,
+  Display,
+  Switch,
+  PlayPause,
+  Reset,
+};
+
+// Re-export types for convenience
+export type { ChessClockRootProps } from "./parts/Root";
+export type { ChessClockDisplayProps } from "./parts/Display";
+export type { ChessClockControlProps } from "./parts/Switch";
+export type { ChessClockPlayPauseProps } from "./parts/PlayPause";
+export type { ChessClockResetProps } from "./parts/Reset";

package/src/components/ChessClock/parts/Display.tsx

@@ -0,0 +1,69 @@
+import React from "react";
+import type { ClockColor } from "../../../types";
+import { useChessClockContext } from "../../../hooks/useChessClockContext";
+import { formatClockTime } from "../../../utils/formatTime";
+
+export interface ChessClockDisplayProps extends React.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`}
+ * />
+ * ```
+ */
+export const Display = React.forwardRef<HTMLDivElement, ChessClockDisplayProps>(
+  (
+    {
+      color,
+      format = "auto",
+      formatTime: customFormatTime,
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) => {
+    const { times, activePlayer, status, timeout } = useChessClockContext();
+
+    const time = times[color];
+    const isActive = activePlayer === color;
+    const hasTimeout = timeout === color;
+    const isPaused = status === "paused";
+
+    // Format the time for display
+    const formattedTime = customFormatTime
+      ? customFormatTime(time)
+      : formatClockTime(time, format);
+
+    return (
+      <div
+        ref={ref}
+        className={className}
+        style={style}
+        data-clock-color={color}
+        data-clock-active={isActive ? "true" : "false"}
+        data-clock-paused={isPaused ? "true" : "false"}
+        data-clock-timeout={hasTimeout ? "true" : "false"}
+        data-clock-status={status}
+        {...rest}
+      >
+        {formattedTime}
+      </div>
+    );
+  },
+);
+
+Display.displayName = "ChessClock.Display";

package/src/components/ChessClock/parts/PlayPause.tsx

@@ -0,0 +1,190 @@
+import React from "react";
+import type { ReactNode } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { useChessClockContext } from "../../../hooks/useChessClockContext";
+
+// Default content for each clock state
+const DEFAULT_CONTENT = {
+  start: "Start",
+  pause: "Pause",
+  resume: "Resume",
+  delayed: "Start",
+  finished: "Game Over",
+} as const;
+
+/**
+ * Resolves the appropriate content to display based on clock state
+ * and custom content props. Custom content takes precedence over defaults.
+ */
+const resolveContent = (
+  isFinished: boolean,
+  isDelayed: boolean,
+  shouldShowStart: boolean,
+  isPaused: boolean,
+  isRunning: boolean,
+  customContent: {
+    startContent?: ReactNode;
+    pauseContent?: ReactNode;
+    resumeContent?: ReactNode;
+    delayedContent?: ReactNode;
+    finishedContent?: ReactNode;
+  },
+): ReactNode => {
+  if (isFinished) {
+    return customContent.finishedContent ?? DEFAULT_CONTENT.finished;
+  }
+  if (isDelayed) {
+    return customContent.delayedContent ?? DEFAULT_CONTENT.delayed;
+  }
+  if (shouldShowStart) {
+    return customContent.startContent ?? DEFAULT_CONTENT.start;
+  }
+  if (isPaused) {
+    return customContent.resumeContent ?? DEFAULT_CONTENT.resume;
+  }
+  if (isRunning) {
+    return customContent.pauseContent ?? DEFAULT_CONTENT.pause;
+  }
+  return DEFAULT_CONTENT.start;
+};
+
+export interface ChessClockPlayPauseProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "onClick"
+> {
+  asChild?: boolean;
+  children?: ReactNode;
+  onClick?: React.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>
+ * ```
+ */
+export const PlayPause = React.forwardRef<
+  HTMLElement,
+  React.PropsWithChildren<ChessClockPlayPauseProps>
+>(
+  (
+    {
+      asChild = false,
+      startContent,
+      pauseContent,
+      resumeContent,
+      delayedContent,
+      finishedContent,
+      children,
+      onClick,
+      disabled,
+      className,
+      style,
+      type,
+      ...rest
+    },
+    ref,
+  ) => {
+    const { status, methods } = useChessClockContext();
+    const isIdle = status === "idle";
+    const isDelayed = status === "delayed";
+    const isPaused = status === "paused";
+    const isRunning = status === "running";
+    const isFinished = status === "finished";
+
+    // Treat "delayed" like "idle" - clock hasn't started yet
+    const shouldShowStart = isIdle || isDelayed;
+
+    const isDisabled = disabled || isFinished || isDelayed;
+
+    const handleClick = React.useCallback(
+      (e: React.MouseEvent<HTMLElement>) => {
+        if (shouldShowStart) {
+          methods.start();
+        } else if (isPaused) {
+          methods.resume();
+        } else if (isRunning) {
+          methods.pause();
+        }
+        onClick?.(e);
+      },
+      [shouldShowStart, isPaused, isRunning, methods, onClick],
+    );
+
+    // Determine content to render
+    // Priority: children > custom+defaults > all defaults
+    const content =
+      children ??
+      resolveContent(
+        isFinished,
+        isDelayed,
+        shouldShowStart,
+        isPaused,
+        isRunning,
+        {
+          startContent,
+          pauseContent,
+          resumeContent,
+          delayedContent,
+          finishedContent,
+        },
+      );
+
+    return asChild ? (
+      <Slot
+        ref={ref}
+        onClick={handleClick}
+        className={className}
+        style={style}
+        {...{ ...rest, disabled: isDisabled }}
+      >
+        {content}
+      </Slot>
+    ) : (
+      <button
+        ref={ref as React.RefObject<HTMLButtonElement>}
+        type={type || "button"}
+        className={className}
+        style={style}
+        onClick={handleClick}
+        disabled={isDisabled}
+        {...rest}
+      >
+        {content}
+      </button>
+    );
+  },
+);
+
+PlayPause.displayName = "ChessClock.PlayPause";

package/src/components/ChessClock/parts/Reset.tsx

@@ -0,0 +1,90 @@
+import React from "react";
+import type { ReactNode } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { useChessClockContext } from "../../../hooks/useChessClockContext";
+import type { TimeControlInput } from "../../../types";
+
+export interface ChessClockResetProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "onClick"
+> {
+  asChild?: boolean;
+  children?: ReactNode;
+  onClick?: React.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>
+ * ```
+ */
+export const Reset = React.forwardRef<
+  HTMLElement,
+  React.PropsWithChildren<ChessClockResetProps>
+>(
+  (
+    {
+      asChild = false,
+      timeControl,
+      children,
+      onClick,
+      disabled,
+      className,
+      style,
+      type,
+      ...rest
+    },
+    ref,
+  ) => {
+    const { methods, status } = useChessClockContext();
+    const isDisabled = disabled || status === "idle";
+
+    const handleClick = React.useCallback(
+      (e: React.MouseEvent<HTMLElement>) => {
+        methods.reset(timeControl);
+        onClick?.(e);
+      },
+      [methods, timeControl, onClick],
+    );
+
+    return asChild ? (
+      <Slot
+        ref={ref}
+        onClick={handleClick}
+        className={className}
+        style={style}
+        {...{ ...rest, disabled: isDisabled }}
+      >
+        {children}
+      </Slot>
+    ) : (
+      <button
+        ref={ref as React.RefObject<HTMLButtonElement>}
+        type={type || "button"}
+        className={className}
+        style={style}
+        onClick={handleClick}
+        disabled={isDisabled}
+        {...rest}
+      >
+        {children}
+      </button>
+    );
+  },
+);
+
+Reset.displayName = "ChessClock.Reset";

package/src/components/ChessClock/parts/Root.tsx

@@ -0,0 +1,37 @@
+import React from "react";
+import type { ReactNode } from "react";
+import { ChessClockContext } from "../../../hooks/useChessClockContext";
+import { useChessClock } from "../../../hooks/useChessClock";
+import type { TimeControlConfig } from "../../../types";
+
+export interface ChessClockRootProps {
+  timeControl: TimeControlConfig;
+  children: ReactNode;
+}
+
+/**
+ * ChessClock.Root - Context provider for chess clock components
+ * Manages clock state and provides it to child components
+ *
+ * @example
+ * ```tsx
+ * <ChessClock.Root timeControl={{ time: "5+3" }}>
+ *   <ChessClock.Display color="white" />
+ *   <ChessClock.Display color="black" />
+ * </ChessClock.Root>
+ * ```
+ */
+export const Root: React.FC<React.PropsWithChildren<ChessClockRootProps>> = ({
+  timeControl,
+  children,
+}) => {
+  const clockState = useChessClock(timeControl);
+
+  return (
+    <ChessClockContext.Provider value={clockState}>
+      {children}
+    </ChessClockContext.Provider>
+  );
+};
+
+Root.displayName = "ChessClock.Root";

package/src/components/ChessClock/parts/Switch.tsx

@@ -0,0 +1,84 @@
+import React from "react";
+import type { ReactNode } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { useChessClockContext } from "../../../hooks/useChessClockContext";
+
+export interface ChessClockControlProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "onClick"
+> {
+  asChild?: boolean;
+  children?: ReactNode;
+  onClick?: React.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>
+ * ```
+ */
+export const Switch = React.forwardRef<
+  HTMLElement,
+  React.PropsWithChildren<ChessClockControlProps>
+>(
+  (
+    {
+      asChild = false,
+      children,
+      onClick,
+      disabled,
+      className,
+      style,
+      type,
+      ...rest
+    },
+    ref,
+  ) => {
+    const { methods, status } = useChessClockContext();
+    const isDisabled = disabled || status === "finished" || status === "idle";
+
+    const handleClick = React.useCallback(
+      (e: React.MouseEvent<HTMLElement>) => {
+        methods.switch();
+        onClick?.(e);
+      },
+      [methods, onClick],
+    );
+
+    return asChild ? (
+      <Slot
+        ref={ref}
+        onClick={handleClick}
+        className={className}
+        style={style}
+        {...{ ...rest, disabled: isDisabled }}
+      >
+        {children}
+      </Slot>
+    ) : (
+      <button
+        ref={ref as React.RefObject<HTMLButtonElement>}
+        type={type || "button"}
+        className={className}
+        style={style}
+        onClick={handleClick}
+        disabled={isDisabled}
+        {...rest}
+      >
+        {children}
+      </button>
+    );
+  },
+);
+
+Switch.displayName = "ChessClock.Switch";

package/src/components/ChessClock/parts/__tests__/Display.test.tsx

@@ -0,0 +1,149 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { ChessClock } from "../../index";
+
+describe("ChessClock.Display", () => {
+  it("should render white player time", () => {
+    render(
+      <ChessClock.Root timeControl={{ time: "5+0" }}>
+        <ChessClock.Display color="white" data-testid="white-clock" />
+      </ChessClock.Root>,
+    );
+
+    const display = screen.getByTestId("white-clock");
+    expect(display).toBeInTheDocument();
+    expect(display).toHaveTextContent("5:00");
+  });
+
+  it("should render black player time", () => {
+    render(
+      <ChessClock.Root timeControl={{ time: "10+5" }}>
+        <ChessClock.Display color="black" data-testid="black-clock" />
+      </ChessClock.Root>,
+    );
+
+    const display = screen.getByTestId("black-clock");
+    expect(display).toHaveTextContent("10:00");
+  });
+
+  it("should include data attributes", () => {
+    render(
+      <ChessClock.Root timeControl={{ time: "5+0" }}>
+        <ChessClock.Display color="white" data-testid="clock" />
+      </ChessClock.Root>,
+    );
+
+    const display = screen.getByTestId("clock");
+    expect(display).toHaveAttribute("data-clock-color", "white");
+    expect(display).toHaveAttribute("data-clock-active", "false");
+    expect(display).toHaveAttribute("data-clock-paused", "false");
+    expect(display).toHaveAttribute("data-clock-timeout", "false");
+    expect(display).toHaveAttribute("data-clock-status", "delayed"); // default clockStart is "delayed"
+  });
+
+  it("should show active clock when clock is running", () => {
+    render(
+      <ChessClock.Root timeControl={{ time: "5+0", clockStart: "immediate" }}>
+        <ChessClock.Display color="white" data-testid="white-clock" />
+        <ChessClock.Display color="black" data-testid="black-clock" />
+      </ChessClock.Root>,
+    );
+
+    const whiteClock = screen.getByTestId("white-clock");
+    const blackClock = screen.getByTestId("black-clock");
+
+    expect(whiteClock).toHaveAttribute("data-clock-active", "true");
+    expect(blackClock).toHaveAttribute("data-clock-active", "false");
+  });
+
+  it("should support custom className", () => {
+    render(
+      <ChessClock.Root timeControl={{ time: "5+0" }}>
+        <ChessClock.Display
+          color="white"
+          className="custom-class"
+          data-testid="clock"
+        />
+      </ChessClock.Root>,
+    );
+
+    expect(screen.getByTestId("clock")).toHaveClass("custom-class");
+  });
+
+  it("should support custom style", () => {
+    render(
+      <ChessClock.Root timeControl={{ time: "5+0" }}>
+        <ChessClock.Display
+          color="white"
+          style={{ fontSize: "24px" }}
+          data-testid="clock"
+        />
+      </ChessClock.Root>,
+    );
+
+    expect(screen.getByTestId("clock")).toHaveStyle({ fontSize: "24px" });
+  });
+
+  describe("format prop", () => {
+    it("should format as mm:ss", () => {
+      render(
+        <ChessClock.Root timeControl={{ time: "5+0" }}>
+          <ChessClock.Display
+            color="white"
+            format="mm:ss"
+            data-testid="clock"
+          />
+        </ChessClock.Root>,
+      );
+
+      expect(screen.getByTestId("clock")).toHaveTextContent("5:00");
+    });
+
+    it("should format as ss.d", () => {
+      render(
+        <ChessClock.Root timeControl={{ time: "5+0" }}>
+          <ChessClock.Display color="white" format="ss.d" data-testid="clock" />
+        </ChessClock.Root>,
+      );
+
+      expect(screen.getByTestId("clock")).toHaveTextContent("300.0");
+    });
+
+    it("should format as hh:mm:ss for long times", () => {
+      render(
+        <ChessClock.Root timeControl={{ time: "90+30" }}>
+          <ChessClock.Display
+            color="white"
+            format="hh:mm:ss"
+            data-testid="clock"
+          />
+        </ChessClock.Root>,
+      );
+
+      expect(screen.getByTestId("clock")).toHaveTextContent("1:30:00");
+    });
+  });
+
+  describe("formatTime prop", () => {
+    it("should use custom formatTime function", () => {
+      const customFormat = jest.fn((ms) => `${Math.ceil(ms / 1000)}s`);
+
+      render(
+        <ChessClock.Root timeControl={{ time: "5+0" }}>
+          <ChessClock.Display
+            color="white"
+            formatTime={customFormat}
+            data-testid="clock"
+          />
+        </ChessClock.Root>,
+      );
+
+      expect(screen.getByTestId("clock")).toHaveTextContent("300s");
+      expect(customFormat).toHaveBeenCalledWith(300_000);
+    });
+  });
+
+  it("should have displayName", () => {
+    expect(ChessClock.Display.displayName).toBe("ChessClock.Display");
+  });
+});