@alepot55/chessboardjs 2.2.1 → 2.3.2

package/src/errors/messages.js

@@ -0,0 +1,189 @@
+/**
+ * Error messages and error handling utilities
+ * @module errors/messages
+ * @since 2.0.0
+ */
+
+/**
+ * Error codes for categorizing different types of errors
+ * @type {Object.<string, string>}
+ * @readonly
+ */
+export const ERROR_CODES = Object.freeze({
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    CONFIG_ERROR: 'CONFIG_ERROR',
+    MOVE_ERROR: 'MOVE_ERROR',
+    DOM_ERROR: 'DOM_ERROR',
+    ANIMATION_ERROR: 'ANIMATION_ERROR',
+    PIECE_ERROR: 'PIECE_ERROR',
+    INITIALIZATION_ERROR: 'INITIALIZATION_ERROR',
+    POSITION_ERROR: 'POSITION_ERROR',
+    FEN_ERROR: 'FEN_ERROR',
+    SQUARE_ERROR: 'SQUARE_ERROR',
+    THEME_ERROR: 'THEME_ERROR',
+    NETWORK_ERROR: 'NETWORK_ERROR'
+});
+
+/**
+ * Standardized error messages for the chessboard application
+ * @type {Object.<string, string>}
+ * @readonly
+ */
+export const ERROR_MESSAGES = Object.freeze({
+    // Position and FEN related
+    invalid_position: 'Invalid position: ',
+    invalid_fen: 'Invalid FEN string: ',
+    position_load_failed: 'Failed to load position: ',
+    
+    // DOM and UI related
+    invalid_id_div: 'Board container not found: ',
+    invalid_value: 'Invalid value: ',
+    dom_operation_failed: 'DOM operation failed: ',
+    element_not_found: 'Element not found: ',
+    
+    // Piece related
+    invalid_piece: 'Invalid piece notation: ',
+    invalid_square: 'Invalid square notation: ',
+    invalid_piecesPath: 'Invalid pieces path: ',
+    piece_operation_failed: 'Piece operation failed: ',
+    
+    // Board configuration
+    invalid_orientation: 'Invalid orientation: ',
+    invalid_color: 'Invalid color: ',
+    invalid_mode: 'Invalid mode: ',
+    invalid_dropOffBoard: 'Invalid dropOffBoard setting: ',
+    invalid_size: 'Invalid size: ',
+    invalid_movableColors: 'Invalid movableColors setting: ',
+    
+    // Animation related
+    invalid_snapbackTime: 'Invalid snapbackTime: ',
+    invalid_snapbackAnimation: 'Invalid snapbackAnimation: ',
+    invalid_fadeTime: 'Invalid fadeTime: ',
+    invalid_fadeAnimation: 'Invalid fadeAnimation: ',
+    invalid_ratio: 'Invalid ratio: ',
+    invalid_animationStyle: 'Invalid animationStyle: ',
+    animation_failed: 'Animation failed: ',
+    
+    // Event handlers
+    invalid_onMove: 'Invalid onMove callback: ',
+    invalid_onMoveEnd: 'Invalid onMoveEnd callback: ',
+    invalid_onChange: 'Invalid onChange callback: ',
+    invalid_onDragStart: 'Invalid onDragStart callback: ',
+    invalid_onDragMove: 'Invalid onDragMove callback: ',
+    invalid_onDrop: 'Invalid onDrop callback: ',
+    invalid_onSnapbackEnd: 'Invalid onSnapbackEnd callback: ',
+    callback_execution_failed: 'Callback execution failed: ',
+    
+    // Visual styling
+    invalid_whiteSquare: 'Invalid whiteSquare color: ',
+    invalid_blackSquare: 'Invalid blackSquare color: ',
+    invalid_highlight: 'Invalid highlight color: ',
+    invalid_selectedSquareWhite: 'Invalid selectedSquareWhite color: ',
+    invalid_selectedSquareBlack: 'Invalid selectedSquareBlack color: ',
+    invalid_movedSquareWhite: 'Invalid movedSquareWhite color: ',
+    invalid_movedSquareBlack: 'Invalid movedSquareBlack color: ',
+    invalid_choiceSquare: 'Invalid choiceSquare color: ',
+    invalid_coverSquare: 'Invalid coverSquare color: ',
+    invalid_hintColor: 'Invalid hintColor: ',
+    
+    // Move related
+    invalid_move: 'Invalid move: ',
+    invalid_move_format: 'Invalid move format: ',
+    move_execution_failed: 'Move execution failed: ',
+    illegal_move: 'Illegal move: ',
+    square_no_piece: 'No piece found on square: ',
+    move_validation_failed: 'Move validation failed: ',
+    
+    // Game state
+    game_over: 'Game is over',
+    invalid_turn: 'Invalid turn: ',
+    position_validation_failed: 'Position validation failed: ',
+    
+    // Theme and assets
+    theme_load_failed: 'Theme loading failed: ',
+    asset_load_failed: 'Asset loading failed: ',
+    invalid_theme: 'Invalid theme: ',
+    
+    // Network and resources
+    network_error: 'Network error: ',
+    resource_not_found: 'Resource not found: ',
+    timeout_error: 'Operation timed out: ',
+    
+    // General errors
+    initialization_failed: 'Initialization failed: ',
+    operation_failed: 'Operation failed: ',
+    invalid_state: 'Invalid state: ',
+    memory_limit_exceeded: 'Memory limit exceeded',
+    performance_degraded: 'Performance degraded: '
+});
+
+/**
+ * Error severity levels
+ * @type {Object.<string, string>}
+ * @readonly
+ */
+export const ERROR_SEVERITY = Object.freeze({
+    LOW: 'LOW',
+    MEDIUM: 'MEDIUM',
+    HIGH: 'HIGH',
+    CRITICAL: 'CRITICAL'
+});
+
+/**
+ * Maps error codes to their severity levels
+ * @type {Object.<string, string>}
+ * @readonly
+ */
+export const ERROR_SEVERITY_MAP = Object.freeze({
+    [ERROR_CODES.VALIDATION_ERROR]: ERROR_SEVERITY.MEDIUM,
+    [ERROR_CODES.CONFIG_ERROR]: ERROR_SEVERITY.HIGH,
+    [ERROR_CODES.MOVE_ERROR]: ERROR_SEVERITY.LOW,
+    [ERROR_CODES.DOM_ERROR]: ERROR_SEVERITY.HIGH,
+    [ERROR_CODES.ANIMATION_ERROR]: ERROR_SEVERITY.LOW,
+    [ERROR_CODES.PIECE_ERROR]: ERROR_SEVERITY.MEDIUM,
+    [ERROR_CODES.INITIALIZATION_ERROR]: ERROR_SEVERITY.CRITICAL,
+    [ERROR_CODES.POSITION_ERROR]: ERROR_SEVERITY.MEDIUM,
+    [ERROR_CODES.FEN_ERROR]: ERROR_SEVERITY.MEDIUM,
+    [ERROR_CODES.SQUARE_ERROR]: ERROR_SEVERITY.MEDIUM,
+    [ERROR_CODES.THEME_ERROR]: ERROR_SEVERITY.LOW,
+    [ERROR_CODES.NETWORK_ERROR]: ERROR_SEVERITY.MEDIUM
+});
+
+/**
+ * Utility function to get error severity
+ * @param {string} errorCode - Error code
+ * @returns {string} Error severity level
+ */
+export function getErrorSeverity(errorCode) {
+    return ERROR_SEVERITY_MAP[errorCode] || ERROR_SEVERITY.MEDIUM;
+}
+
+/**
+ * Utility function to format error message
+ * @param {string} messageKey - Message key from ERROR_MESSAGES
+ * @param {string} [details] - Additional details
+ * @returns {string} Formatted error message
+ */
+export function formatErrorMessage(messageKey, details = '') {
+    const message = ERROR_MESSAGES[messageKey];
+    if (!message) {
+        return `Unknown error: ${messageKey}${details ? ` - ${details}` : ''}`;
+    }
+    return `${message}${details}`;
+}
+
+/**
+ * Utility function to create error context
+ * @param {string} operation - Operation that failed
+ * @param {Object} [data] - Additional context data
+ * @returns {Object} Error context object
+ */
+export function createErrorContext(operation, data = {}) {
+    return {
+        operation,
+        timestamp: new Date().toISOString(),
+        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'Unknown',
+        url: typeof window !== 'undefined' ? window.location.href : 'Unknown',
+        ...data
+    };
+}

package/src/index.js

@@ -0,0 +1,103 @@
+/**
+ * Chessboard.js - A beautiful, customizable chessboard widget
+ * Main entry point for the library
+ * 
+ * @version 2.2.1
+ * @author alepot55
+ * @license ISC
+ */
+
+// Core components
+export { 
+    Chessboard, 
+    ChessboardConfig, 
+    ChessboardFactory,
+    chessboardFactory,
+    createChessboard,
+    createChessboardFromTemplate 
+} from './core/index.js';
+
+// Component exports
+export { default as Square } from './components/Square.js';
+export { default as Piece } from './components/Piece.js';
+export { default as Move } from './components/Move.js';
+
+// Service exports for advanced usage
+export { 
+    AnimationService,
+    BoardService,
+    CoordinateService,
+    EventService,
+    MoveService,
+    PieceService,
+    PositionService,
+    ValidationService
+} from './services/index.js';
+
+// Constants exports
+export * from './constants/index.js';
+
+// Error handling exports
+export { 
+    ChessboardError, 
+    ValidationError, 
+    ConfigurationError,
+    MoveError,
+    DOMError,
+    PieceError
+} from './errors/index.js';
+
+// Utility exports
+export { Chess, validateFen } from './utils/chess.js';
+export { 
+    PerformanceMonitor,
+    throttle,
+    debounce,
+    rafThrottle,
+    setTransform,
+    resetTransform,
+    batchDOMOperations,
+    isElementVisible,
+    getMemoryUsage
+} from './utils/performance.js';
+export * from './utils/coordinates.js';
+export { 
+    isValidPiece,
+    isValidPosition,
+    validateFenFormat,
+    validateMove,
+    validateConfig,
+    batchValidate,
+    clearValidationCache,
+    getValidationCacheStats
+} from './utils/validation.js';
+export * from './utils/animations.js';
+
+// Logging system exports
+export { 
+    Logger,
+    logger,
+    createLogger,
+    LOG_LEVELS
+} from './utils/logger.js';
+
+// Default export for IIFE compatibility
+import { Chessboard as ChessboardClass } from './core/index.js';
+export default ChessboardClass;
+
+// Version information
+export const version = '2.2.1';
+export const build = process.env.BUILD_NUMBER || 'dev';
+export const buildDate = process.env.BUILD_DATE || new Date().toISOString();
+
+// Library information
+export const info = {
+    name: 'Chessboard.js',
+    version,
+    build,
+    buildDate,
+    author: 'alepot55',
+    license: 'ISC',
+    repository: 'https://github.com/alepot55/Chessboardjs',
+    homepage: 'https://chessboardjs.com'
+};

package/src/services/AnimationService.js

@@ -0,0 +1,180 @@
+/**
+ * Service for managing animations and transitions
+ * @module services/AnimationService
+ * @since 2.0.0
+ */
+
+/**
+ * Service responsible for coordinating animations and transitions
+ * @class
+ */
+export class AnimationService {
+    /**
+     * Creates a new AnimationService instance
+     * @param {ChessboardConfig} config - Board configuration
+     */
+    constructor(config) {
+        this.config = config;
+        this.activeAnimations = new Map();
+        this.animationId = 0;
+    }
+
+    /**
+     * Creates a timing function for animations
+     * @param {string} [type='ease'] - Animation type
+     * @returns {Function} Timing function
+     */
+    createTimingFunction(type = 'ease') {
+        return (elapsed, duration) => {
+            const x = elapsed / duration;
+
+            switch (type) {
+                case 'linear':
+                    return x;
+                case 'ease':
+                    return (x ** 2) * (3 - 2 * x);
+                case 'ease-in':
+                    return x ** 2;
+                case 'ease-out':
+                    return -1 * (x - 1) ** 2 + 1;
+                case 'ease-in-out':
+                    return (x < 0.5) ? 2 * x ** 2 : 4 * x - 2 * x ** 2 - 1;
+                default:
+                    return x;
+            }
+        };
+    }
+
+    /**
+     * Animates an element with given properties
+     * @param {HTMLElement} element - Element to animate
+     * @param {Object} properties - Properties to animate
+     * @param {number} duration - Animation duration in milliseconds
+     * @param {string} [easing='ease'] - Easing function
+     * @param {Function} [callback] - Callback when animation completes
+     * @returns {number} Animation ID
+     */
+    animate(element, properties, duration, easing = 'ease', callback) {
+        const animationId = ++this.animationId;
+        const timingFunction = this.createTimingFunction(easing);
+        const startTime = performance.now();
+        const startValues = {};
+
+        // Store initial values
+        Object.keys(properties).forEach(prop => {
+            startValues[prop] = this._getInitialValue(element, prop);
+        });
+
+        const animate = (currentTime) => {
+            const elapsed = currentTime - startTime;
+            const progress = Math.min(elapsed / duration, 1);
+            const easedProgress = timingFunction(elapsed, duration);
+
+            // Apply animated values
+            Object.keys(properties).forEach(prop => {
+                const startValue = startValues[prop];
+                const endValue = properties[prop];
+                const currentValue = this._interpolateValue(startValue, endValue, easedProgress);
+                this._applyValue(element, prop, currentValue);
+            });
+
+            if (progress < 1 && this.activeAnimations.has(animationId)) {
+                requestAnimationFrame(animate);
+            } else {
+                this.activeAnimations.delete(animationId);
+                if (callback) callback();
+            }
+        };
+
+        this.activeAnimations.set(animationId, { element, animate, callback });
+        requestAnimationFrame(animate);
+
+        return animationId;
+    }
+
+    /**
+     * Cancels an animation
+     * @param {number} animationId - Animation ID to cancel
+     */
+    cancel(animationId) {
+        if (this.activeAnimations.has(animationId)) {
+            this.activeAnimations.delete(animationId);
+        }
+    }
+
+    /**
+     * Cancels all animations
+     */
+    cancelAll() {
+        this.activeAnimations.clear();
+    }
+
+    /**
+     * Gets initial value for a property
+     * @private
+     * @param {HTMLElement} element - Element
+     * @param {string} property - Property name
+     * @returns {number} Initial value
+     */
+    _getInitialValue(element, property) {
+        if (!element || !element.style) return 0;
+        switch (property) {
+            case 'opacity':
+                return parseFloat(getComputedStyle(element).opacity) || 1;
+            case 'left':
+                return parseFloat(element.style.left) || 0;
+            case 'top':
+                return parseFloat(element.style.top) || 0;
+            case 'scale':
+                return 1;
+            default:
+                return 0;
+        }
+    }
+
+    /**
+     * Interpolates between two values
+     * @private
+     * @param {number} start - Start value
+     * @param {number} end - End value
+     * @param {number} progress - Progress (0-1)
+     * @returns {number} Interpolated value
+     */
+    _interpolateValue(start, end, progress) {
+        return start + (end - start) * progress;
+    }
+
+    /**
+     * Applies animated value to element
+     * @private
+     * @param {HTMLElement} element - Element
+     * @param {string} property - Property name
+     * @param {number} value - Value to apply
+     */
+    _applyValue(element, property, value) {
+        if (!element || !element.style) return;
+        switch (property) {
+            case 'opacity':
+                element.style.opacity = value;
+                break;
+            case 'left':
+                element.style.left = value + 'px';
+                break;
+            case 'top':
+                element.style.top = value + 'px';
+                break;
+            case 'scale':
+                element.style.transform = `scale(${value})`;
+                break;
+            default:
+                element.style[property] = value;
+        }
+    }
+
+    /**
+     * Cleans up resources
+     */
+    destroy() {
+        this.cancelAll();
+    }
+}

package/src/services/BoardService.js

@@ -0,0 +1,156 @@
+/**
+ * Service for managing board setup and DOM operations
+ * @module services/BoardService
+ * @since 2.0.0
+ */
+
+import { BOARD_SIZE } from '../constants/positions.js';
+import { DOMError, ValidationError } from '../errors/ChessboardError.js';
+import { ERROR_MESSAGES } from '../errors/messages.js';
+import Square from '../components/Square.js';
+
+/**
+ * Service responsible for board DOM manipulation and setup
+ * @class
+ */
+export class BoardService {
+    /**
+     * Creates a new BoardService instance
+     * @param {ChessboardConfig} config - Board configuration
+     */
+    constructor(config) {
+        this.config = config;
+        this.element = null;
+        this.squares = {};
+    }
+
+    /**
+     * Builds the board DOM element and attaches it to the configured container
+     * @throws {DOMError} When the container element cannot be found
+     */
+    buildBoard() {
+        console.log('BoardService.buildBoard: Looking for element with ID:', this.config.id_div);
+
+        this.element = document.getElementById(this.config.id_div);
+        if (!this.element) {
+            throw new DOMError(ERROR_MESSAGES.invalid_id_div + this.config.id_div, this.config.id_div);
+        }
+
+        this.resize(this.config.size);
+        this.element.className = "board";
+    }
+
+    /**
+     * Creates all 64 squares and adds them to the board
+     * @param {Function} coordConverter - Function to convert row/col to real coordinates
+     */
+    buildSquares(coordConverter) {
+        for (let row = 0; row < BOARD_SIZE.ROWS; row++) {
+            for (let col = 0; col < BOARD_SIZE.COLS; col++) {
+                const [squareRow, squareCol] = coordConverter(row, col);
+                const square = new Square(squareRow, squareCol);
+
+                this.squares[square.getId()] = square;
+                this.element.appendChild(square.element);
+            }
+        }
+    }
+
+    /**
+     * Removes all squares from the board and cleans up their resources
+     * Best practice: always destroy JS objects and DOM nodes, and clear references.
+     */
+    removeSquares() {
+        for (const square of Object.values(this.squares)) {
+            // Always call destroy to remove DOM and clear piece reference
+            square.destroy();
+        }
+        this.squares = {};
+    }
+
+    /**
+     * Removes all content from the board element
+     * Best practice: clear DOM and force element to be re-fetched on next build.
+     */
+    removeBoard() {
+        if (this.element) {
+            this.element.innerHTML = '';
+            this.element = null;
+        }
+    }
+
+    /**
+     * Resizes the board to the specified size
+     * @param {number|string} value - Size in pixels or 'auto'
+     * @throws {ValidationError} When size value is invalid
+     */
+    resize(value) {
+        if (value === 'auto') {
+            const size = this._calculateAutoSize();
+            this.resize(size);
+        } else if (typeof value !== 'number') {
+            throw new ValidationError(ERROR_MESSAGES.invalid_value + value, 'size', value);
+        } else {
+            document.documentElement.style.setProperty('--dimBoard', value + 'px');
+        }
+    }
+
+    /**
+     * Calculates the optimal size when 'auto' is specified
+     * @private
+     * @returns {number} Calculated size in pixels
+     */
+    _calculateAutoSize() {
+        if (!this.element) return 400; // Default fallback
+
+        const { offsetWidth, offsetHeight } = this.element;
+
+        if (offsetWidth === 0) {
+            return offsetHeight || 400;
+        } else if (offsetHeight === 0) {
+            return offsetWidth;
+        } else {
+            return Math.min(offsetWidth, offsetHeight);
+        }
+    }
+
+    /**
+     * Gets a square by its ID
+     * @param {string} squareId - Square identifier (e.g., 'e4')
+     * @returns {Square|null} The square or null if not found
+     */
+    getSquare(squareId) {
+        return this.squares[squareId] || null;
+    }
+
+    /**
+     * Gets all squares
+     * @returns {Object.<string, Square>} All squares indexed by ID
+     */
+    getAllSquares() {
+        return { ...this.squares };
+    }
+
+    /**
+     * Applies a method to all squares
+     * @param {string} methodName - Name of the method to call on each square
+     * @param {...*} args - Arguments to pass to the method
+     */
+    applyToAllSquares(methodName, ...args) {
+        for (const square of Object.values(this.squares)) {
+            if (typeof square[methodName] === 'function') {
+                square[methodName](...args);
+            }
+        }
+    }
+
+    /**
+     * Cleans up all resources
+     */
+    destroy() {
+        this.removeSquares();
+        this.removeBoard();
+        this.element = null;
+        this.squares = {};
+    }
+}