@chessviewer-org/chess-viewer 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,369 @@
+type PieceSymbol = 'P' | 'N' | 'B' | 'R' | 'Q' | 'K' | 'p' | 'n' | 'b' | 'r' | 'q' | 'k' | '';
+type BoardMatrix = PieceSymbol[][];
+interface ValidationResult {
+    isValid: boolean;
+    errorMessage: string | null;
+}
+declare const MAX_FEN_LENGTH = 93;
+declare class FENParseError extends Error {
+    constructor(message: string);
+}
+declare function parseFEN(fenString: string): BoardMatrix;
+declare function validateFEN(fen: string): boolean;
+declare function getFENValidationError(fen: string): string;
+declare function validateFENDetailed(fen: string): ValidationResult;
+declare function createEmptyBoard(): BoardMatrix;
+declare function boardToFEN(board: BoardMatrix): string;
+declare function isBoardEmpty(board: BoardMatrix): boolean;
+declare function pieceToName(piece: string): string;
+declare function describeBoardPosition(board: BoardMatrix, flipped?: boolean): string;
+
+/** Side to move in a chess position. */
+type ActiveColor = 'w' | 'b';
+/**
+ * A fully parsed FEN record — all six fields of a standard FEN string.
+ *
+ * @see https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation
+ */
+interface FENRecord {
+    /** Piece placement as an 8×8 matrix (rank 8 first). */
+    board: BoardMatrix;
+    /** Side to move. */
+    activeColor: ActiveColor;
+    /** Castling availability, e.g. `'KQkq'`, or `'-'` if none. */
+    castling: string;
+    /** En passant target square, e.g. `'e3'`, or `'-'` if none. */
+    enPassant: string;
+    /** Halfmove clock (moves since last capture or pawn advance). */
+    halfmove: number;
+    /** Fullmove number (starts at 1, increments after Black's move). */
+    fullmove: number;
+}
+/**
+ * Parses a complete FEN string into its six structured fields.
+ *
+ * Unlike {@link parseFEN}, which returns only the board, this parses the full
+ * record including side to move, castling rights, en passant target, and clocks.
+ * Missing trailing fields are filled with standard defaults
+ * (`w`, `-`, `-`, `0`, `1`) so that piece-placement-only strings parse too.
+ *
+ * @param fen - Full or partial FEN string.
+ * @returns The parsed {@link FENRecord}.
+ * @throws {FENParseError} If any present field is malformed.
+ */
+declare function parseFENRecord(fen: string): FENRecord;
+/**
+ * Serializes a {@link FENRecord} back into a canonical six-field FEN string.
+ *
+ * @param record - The record to serialize. Any subset of metadata fields may be
+ *   omitted; standard defaults are applied for those left out.
+ * @returns A full FEN string.
+ */
+declare function buildFENRecord(record: Partial<FENRecord> & {
+    board: BoardMatrix;
+}): string;
+/**
+ * Returns a new FEN record with the side to move toggled.
+ * Pure — does not mutate the input.
+ */
+declare function toggleActiveColor(record: FENRecord): FENRecord;
+/**
+ * Extracts only the piece-placement field from a full FEN string.
+ * Returns the input trimmed if it has no whitespace.
+ */
+declare function fenPlacementField(fen: string): string;
+/**
+ * Normalizes a FEN string to its canonical six-field form, filling defaults
+ * for any missing metadata. Throws if the placement field is invalid.
+ */
+declare function normalizeFEN(fen: string): string;
+
+/** A square reference: either algebraic (`'e4'`) or `[row, col]` matrix indices. */
+type SquareRef = string | readonly [number, number];
+/** Returns a deep copy of a board matrix. Safe to mutate the result. */
+declare function cloneBoard(board: BoardMatrix): BoardMatrix;
+/**
+ * Returns the piece on a square, or `''` for an empty square and `null` for an
+ * out-of-range reference.
+ */
+declare function getPieceAt(board: BoardMatrix, square: SquareRef): PieceSymbol | null;
+/**
+ * Returns a new board with `piece` placed on `square`. Pure — the input board
+ * is not mutated. An out-of-range square returns the board unchanged.
+ */
+declare function setPieceAt(board: BoardMatrix, square: SquareRef, piece: PieceSymbol): BoardMatrix;
+/** Returns a new board with `square` cleared. Pure. */
+declare function removePieceAt(board: BoardMatrix, square: SquareRef): BoardMatrix;
+/**
+ * Returns a new board with the piece moved from `from` to `to`, overwriting any
+ * piece on the destination. Pure. No-ops if `from` is empty or either ref is
+ * out of range.
+ */
+declare function movePiece(board: BoardMatrix, from: SquareRef, to: SquareRef): BoardMatrix;
+/**
+ * Returns a new board rotated 180° (equivalent to viewing it from the other
+ * side). Pure.
+ */
+declare function flipBoard(board: BoardMatrix): BoardMatrix;
+/** A piece on a specific square. */
+interface PiecePlacement {
+    square: string;
+    piece: PieceSymbol;
+}
+/** Lists every occupied square with its piece, in reading order (a8 → h1). */
+declare function listPieces(board: BoardMatrix): PiecePlacement[];
+/** Counts how many pieces of each symbol are on the board. */
+declare function countPieces(board: BoardMatrix): Record<string, number>;
+/** Material balance from White's perspective (positive = White ahead). */
+declare function materialBalance(board: BoardMatrix): number;
+/** Finds the square of the king of the given color, or `null` if absent. */
+declare function findKing(board: BoardMatrix, color: 'w' | 'b'): string | null;
+/**
+ * Checks that the board has exactly one king of each color — the minimum
+ * legality requirement for a renderable position.
+ */
+declare function hasBothKings(board: BoardMatrix): boolean;
+
+interface DiagramOptions {
+    /** FEN string (piece placement only or full FEN) */
+    fen: string;
+    /** Light square color (hex, default '#f0d9b5') */
+    lightSquare?: string;
+    /** Dark square color (hex, default '#b58863') */
+    darkSquare?: string;
+    /** Board size in pixels (default 400) */
+    size?: number;
+    /** Whether to show rank/file coordinates (default false) */
+    showCoords?: boolean;
+    /** Whether to flip the board (black at bottom, default false) */
+    flipped?: boolean;
+    /** Whether to show a thin outer frame (default false) */
+    showFrame?: boolean;
+    /**
+     * Color of the rank/file coordinate labels. Accepts a hex string or the
+     * names `'white'` / `'black'` (e.g. the result of `themeCoordinateColor`).
+     * Default '#000000'.
+     */
+    coordColor?: string;
+    /** Accessible label for the SVG (default 'Chess position') */
+    label?: string;
+}
+/**
+ * Generates a self-contained SVG chess diagram from a FEN string.
+ * Works in Node.js and browsers — no DOM required.
+ *
+ * @param options - Diagram configuration
+ * @returns SVG markup string
+ * @throws If the FEN string is invalid
+ */
+declare function generateDiagram(options: DiagramOptions): string;
+
+declare const PIECES: Record<string, string>;
+declare function getPieceSVG(fenChar: string): string | null;
+
+declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+};
+declare function rgbToHex(r: number, g: number, b: number): string;
+declare function rgbToHsv(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    v: number;
+};
+declare function hsvToRgb(h: number, s: number, v: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+declare function hexToHsv(hex: string): {
+    h: number;
+    s: number;
+    v: number;
+};
+declare function hsvToHex(h: number, s: number, v: number): string;
+/**
+ * Returns relative luminance of a hex color (WCAG 2.1 formula).
+ */
+declare function relativeLuminance(hex: string): number;
+/**
+ * Returns WCAG 2.1 contrast ratio between two hex colors.
+ * Range: 1 (no contrast) to 21 (black on white).
+ */
+declare function contrastRatio(hex1: string, hex2: string): number;
+/**
+ * Returns 'white' or 'black' — whichever has higher contrast against the given background.
+ */
+declare function bestTextColor(backgroundHex: string): 'white' | 'black';
+
+declare function safeJSONParse<T>(jsonString: string | null | undefined, fallback: T): T;
+declare function sanitizeFileName(fileName?: string | null): string;
+declare function isValidHexColor(color: unknown): color is string;
+declare function sanitizeHexColor(color: unknown, fallback?: string): string;
+declare function sanitizeInput(input: unknown, maxLength?: number): string;
+declare function isRecord(val: unknown): val is Record<string, unknown>;
+
+declare const DEFAULT_LIGHT_SQUARE = "#f0d9b5";
+declare const DEFAULT_DARK_SQUARE = "#b58863";
+declare const STARTING_FEN = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
+declare const EMPTY_FEN = "8/8/8/8/8/8/8/8 w - - 0 1";
+interface PieceSet {
+    id: string;
+    name: string;
+}
+declare const PIECE_SETS: PieceSet[];
+declare const PIECE_SET_POPULARITY: readonly string[];
+interface BoardTheme {
+    name: string;
+    light: string;
+    dark: string;
+}
+declare const BOARD_THEMES: Record<string, BoardTheme>;
+interface QualityPreset {
+    value: number;
+    label: string;
+    description: string;
+    mode: 'print' | 'social';
+    forceCoordinateBorder: boolean;
+    estimatedSize: string;
+}
+declare const QUALITY_PRESETS: QualityPreset[];
+declare const PIECE_MAP: Record<string, string>;
+
+type HistorySource = 'manual' | 'export' | 'drag';
+type ArchiveSource = 'auto' | 'manual';
+type FreshnessStatus = 'green' | 'yellow' | 'red';
+interface BaseHistoryEntry {
+    id: number;
+    fen: string;
+    createdAt: number;
+    lastActiveAt: number;
+    source: HistorySource;
+    isFavorite: boolean;
+}
+interface ActiveHistoryEntry extends BaseHistoryEntry {
+    dragSessionId?: string;
+}
+interface ArchivedHistoryEntry extends BaseHistoryEntry {
+    archivedAt: number;
+    archiveSource: ArchiveSource;
+}
+interface HistoryFilters {
+    fenSearch?: string;
+    dateFrom?: number;
+    dateTo?: number;
+    status?: FreshnessStatus;
+    source?: HistorySource;
+    favoritesOnly?: boolean;
+}
+declare function calculateStatus(lastActiveAt: number): FreshnessStatus;
+declare function createHistoryEntry(fen: string, source: HistorySource, dragSessionId?: string | null): ActiveHistoryEntry;
+declare function touchEntry<T extends BaseHistoryEntry>(entry: T): T;
+declare function sortByMostRecent<T extends {
+    lastActiveAt: number;
+}>(entries: T[]): T[];
+declare function sortArchivedByArchiveDate(entries: ArchivedHistoryEntry[]): ArchivedHistoryEntry[];
+declare function mergeById<T extends {
+    id: number;
+}>(primary: T[], secondary: T[]): T[];
+declare function applyFilters<T extends BaseHistoryEntry>(entries: T[], filters: HistoryFilters): T[];
+interface PartitionResult {
+    active: ActiveHistoryEntry[];
+    toArchive: ActiveHistoryEntry[];
+}
+declare function partitionByArchiveStatus(entries: ActiveHistoryEntry[]): PartitionResult;
+declare function convertToArchivedEntry(entry: ActiveHistoryEntry, archiveSource?: ArchiveSource): ArchivedHistoryEntry;
+
+interface CoordinateParams {
+    fontSize: number;
+    borderSize: number;
+    fontWeight: number;
+    offset: number;
+}
+interface SquareBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    centerX: number;
+    centerY: number;
+}
+/**
+ * Calculates coordinate label display parameters based on board pixel size.
+ */
+declare function getCoordinateParams(boardSize: number): CoordinateParams;
+/**
+ * Calculates the bounding box and center coordinates for a board square.
+ */
+declare function getSquareBounds(rowIndex: number, colIndex: number, squareSize: number, offsetX?: number, offsetY?: number): SquareBounds;
+declare function isLightSquare(row: number, col: number): boolean;
+/**
+ * Returns actual [row, col] accounting for board flip.
+ */
+declare function getDisplayCoordinates(row: number, col: number, flipped: boolean): [number, number];
+/**
+ * Converts a square name (e.g. 'e4') to [row, col] matrix indices (row 0 = rank 8).
+ */
+declare function squareToIndices(square: string): [number, number] | null;
+/**
+ * Converts matrix [row, col] indices to algebraic square name (e.g. 'e4').
+ */
+declare function indicesToSquare(row: number, col: number): string;
+
+/**
+ * Rewrites the DPI metadata of a PNG or JPEG blob.
+ * Works in both browser and Node.js (uses ArrayBuffer/Uint8Array, no DOM needed).
+ */
+declare function changeDPI(blob: Blob, dpi: number, format: 'png' | 'jpeg'): Promise<Blob>;
+
+/** Looks up a board theme by id, or `null` if no such theme exists. */
+declare function getBoardTheme(id: string): BoardTheme | null;
+/** All board theme ids. */
+declare function listThemeIds(): string[];
+/** Looks up a piece set by id, or `null` if not found. */
+declare function getPieceSet(id: string): PieceSet | null;
+/**
+ * Returns the piece sets ordered by curated popularity. Any sets not listed in
+ * {@link PIECE_SET_POPULARITY} are appended in their original order.
+ */
+declare function pieceSetsByPopularity(): PieceSet[];
+/** Looks up a quality preset by its multiplier value, or `null`. */
+declare function getQualityPreset(value: number): QualityPreset | null;
+/** Contrast ratio between a theme's light and dark squares (WCAG 2.1). */
+declare function themeContrast(theme: BoardTheme): number;
+/**
+ * Picks the coordinate-label text color (`'white'` | `'black'`) that reads best
+ * against a theme's dark squares — useful when drawing coordinates inside the
+ * board rather than in a border.
+ */
+declare function themeCoordinateColor(theme: BoardTheme): 'white' | 'black';
+
+/** Pixel dimensions of a raster image. */
+interface ImageDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Reads the pixel dimensions of a PNG or JPEG from its raw bytes, without
+ * decoding the image. Works in Node.js and browsers (operates on
+ * `Uint8Array` / `ArrayBuffer`, no DOM required).
+ *
+ * @param data - The image bytes.
+ * @returns The image dimensions, or `null` if the format is unrecognized or the
+ *   header is truncated.
+ */
+declare function readImageDimensions(data: Uint8Array | ArrayBuffer): ImageDimensions | null;
+/**
+ * Computes the physical print size of an image at a given DPI.
+ *
+ * @param pixels - Dimension in pixels.
+ * @param dpi - Target dots-per-inch.
+ * @returns Size in inches and millimetres.
+ */
+declare function physicalSize(pixels: number, dpi: number): {
+    inches: number;
+    mm: number;
+};
+
+export { type ActiveColor, type ActiveHistoryEntry, type ArchiveSource, type ArchivedHistoryEntry, BOARD_THEMES, type BaseHistoryEntry, type BoardMatrix, type BoardTheme, type CoordinateParams, DEFAULT_DARK_SQUARE, DEFAULT_LIGHT_SQUARE, type DiagramOptions, EMPTY_FEN, FENParseError, type FENRecord, type FreshnessStatus, type HistoryFilters, type HistorySource, type ImageDimensions, MAX_FEN_LENGTH, PIECES, PIECE_MAP, PIECE_SETS, PIECE_SET_POPULARITY, type PartitionResult, type PiecePlacement, type PieceSet, type PieceSymbol, QUALITY_PRESETS, type QualityPreset, STARTING_FEN, type SquareBounds, type SquareRef, type ValidationResult, applyFilters, bestTextColor, boardToFEN, buildFENRecord, calculateStatus, changeDPI, cloneBoard, contrastRatio, convertToArchivedEntry, countPieces, createEmptyBoard, createHistoryEntry, describeBoardPosition, fenPlacementField, findKing, flipBoard, generateDiagram, getBoardTheme, getCoordinateParams, getDisplayCoordinates, getFENValidationError, getPieceAt, getPieceSVG, getPieceSet, getQualityPreset, getSquareBounds, hasBothKings, hexToHsv, hexToRgb, hsvToHex, hsvToRgb, indicesToSquare, isBoardEmpty, isLightSquare, isRecord, isValidHexColor, listPieces, listThemeIds, materialBalance, mergeById, movePiece, normalizeFEN, parseFEN, parseFENRecord, partitionByArchiveStatus, physicalSize, pieceSetsByPopularity, pieceToName, readImageDimensions, relativeLuminance, removePieceAt, rgbToHex, rgbToHsv, safeJSONParse, sanitizeFileName, sanitizeHexColor, sanitizeInput, setPieceAt, sortArchivedByArchiveDate, sortByMostRecent, squareToIndices, themeContrast, themeCoordinateColor, toggleActiveColor, touchEntry, validateFEN, validateFENDetailed };