@react-chess-tools/react-chess-puzzle/dist/index.d.ts

A lightweight, customizable React component library for rendering and interacting with chess puzzles.

import * as React from 'react';
import React__default from 'react';
import { DeepPartial, ChessGameTheme, ChessGame } from '@react-chess-tools/react-chess-game';

/**
 * Puzzle-specific state colors (RGBA color strings)
 */
interface PuzzleStateTheme {
    /** Background color for successful moves */
    success: string;
    /** Background color for failed moves */
    failure: string;
    /** Background color for hint squares */
    hint: string;
}
/**
 * Complete theme configuration for ChessPuzzle component.
 * Extends ChessGameTheme with puzzle-specific colors.
 */
interface ChessPuzzleTheme extends ChessGameTheme {
    puzzle: PuzzleStateTheme;
}
/**
 * Partial theme for puzzle customization - allows overriding only specific properties
 */
type PartialChessPuzzleTheme = DeepPartial<ChessPuzzleTheme>;

type Status = "not-started" | "in-progress" | "solved" | "failed";
type Hint = "none" | "piece" | "move";
type Puzzle = {
    fen: string;
    moves: string[];
    makeFirstMove?: boolean;
};

interface HintProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
    asChild?: boolean;
    /**
     * The puzzle statuses in which the hint button should be visible.
     * @default ["not-started", "in-progress"]
     */
    showOn?: Status[];
}

interface ResetProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, "onReset"> {
    asChild?: boolean;
    puzzle?: Puzzle;
    onReset?: (puzzleContext: ChessPuzzleContextType) => void;
    /**
     * The puzzle statuses in which the reset button should be visible.
     * @default ["failed", "solved"]
     */
    showOn?: Status[];
}

interface PuzzleBoardProps extends React__default.ComponentProps<typeof ChessGame.Board> {
}

type ChessPuzzleContextType = {
    status: Status;
    changePuzzle: (puzzle: Puzzle) => void;
    resetPuzzle: () => void;
    puzzle: Puzzle;
    hint: Hint;
    nextMove?: string | null;
    isPlayerTurn: boolean;
    onHint: () => void;
    puzzleState: Status;
    movesPlayed: number;
    totalMoves: number;
};

interface RootProps {
    puzzle: Puzzle;
    onSolve?: (puzzleContext: ChessPuzzleContextType) => void;
    onFail?: (puzzleContext: ChessPuzzleContextType) => void;
    /** Optional theme configuration. Supports partial themes - only override the colors you need. */
    theme?: PartialChessPuzzleTheme;
    /** When true, any checkmate move solves the puzzle (not just the canonical solution). Defaults to true. */
    solveOnCheckmate?: boolean;
}

declare const ChessPuzzle: {
    Root: React.FC<React.PropsWithChildren<RootProps>>;
    Board: React.ForwardRefExoticComponent<Omit<PuzzleBoardProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
    Reset: React.ForwardRefExoticComponent<ResetProps & {
        children?: React.ReactNode | undefined;
    } & React.RefAttributes<HTMLElement>>;
    Hint: React.ForwardRefExoticComponent<HintProps & {
        children?: React.ReactNode | undefined;
    } & React.RefAttributes<HTMLElement>>;
};

declare const useChessPuzzleContext: () => ChessPuzzleContextType;

/**
 * Default theme for ChessPuzzle component.
 * Extends the default game theme with puzzle-specific colors.
 * These values match the original hardcoded colors for backward compatibility.
 */
declare const defaultPuzzleTheme: ChessPuzzleTheme;

/**
 * Deep merges a partial puzzle theme with the default puzzle theme.
 * Allows users to override only specific theme properties while keeping defaults for the rest.
 *
 * @param partialTheme - Partial theme with only the properties to override
 * @returns Complete puzzle theme with overridden properties merged with defaults
 *
 * @example
 * ```typescript
 * const customTheme = mergePuzzleTheme({
 *   puzzle: { hint: "rgba(0, 255, 255, 0.5)" }
 * });
 * // Returns full puzzle theme with only hint color changed
 * ```
 */
declare const mergePuzzleTheme: (partialTheme?: PartialChessPuzzleTheme) => ChessPuzzleTheme;

/**
 * Context for ChessPuzzle theme
 */
declare const ChessPuzzleThemeContext: React__default.Context<ChessPuzzleTheme>;
/**
 * Hook to access the current ChessPuzzle theme.
 * Returns the default puzzle theme if no ThemeProvider is present.
 */
declare const useChessPuzzleTheme: () => ChessPuzzleTheme;

export { ChessPuzzle, type ChessPuzzleContextType, type ChessPuzzleTheme, ChessPuzzleThemeContext, type Hint, type HintProps, type PartialChessPuzzleTheme, type Puzzle, type PuzzleBoardProps, type PuzzleStateTheme, type ResetProps, type RootProps, type Status, defaultPuzzleTheme, mergePuzzleTheme, useChessPuzzleContext, useChessPuzzleTheme };